83 lines
3.4 KiB
Markdown
83 lines
3.4 KiB
Markdown
# Matrix-Chat-Message
|
|
|
|
## What does this action do?
|
|
|
|
:bulb: This action can send a message to a [Matrix](https://matrix.org/) chat room.
|
|
|
|
## Prerequisites
|
|
You will need the following to successfully setup the action
|
|
- [ ] Account on a Matrix server
|
|
- [ ] Account access token
|
|
- [ ] The internal room ID of the room where you want to send the message
|
|
|
|
### Where to Find those Things?
|
|
|
|
### Account on a Matrix Server
|
|
If you do not have a Matrix account yet or want to register a new one just for this GitHub action check out https://publiclist.anchel.nl/ for a list of public homeservers.
|
|
|
|
The username is the part between `@` and `:` in the MXID while the homeserver is the part after the `:` (in `@someone:example.org` the username is `someone` and the homserver is `example.org`).
|
|
|
|
|
|
### Matrix Access Token
|
|
To get the access token follow the following steps:
|
|
|
|
* Open a [Element web client](https://app.element.io/) (if you use that same client for anything else open it in a private window).
|
|
* Sign in with your username and password.
|
|
* If you enter your username in the MXID format (`@username:server.tld`) it will automatically switch to the correct server.
|
|
* When prompted to `Verify this login` press `Skip` (2x times).
|
|
* As this GitHub Action currently does not support any encryption there is no need to set it up.
|
|
* `Close` the notification that you are not receiving desktop notifications.
|
|
* Click on your username in the top left corner, a menu will open.
|
|
* Select `All settings`, Select `Help & About`, scroll down.
|
|
* Click on the `<click to reveal>` text at the bottom to unconver the access token.
|
|
* Copy the token as it is displayed.
|
|
|
|
### Internal Room ID
|
|
* Use the Element session from the access token step to join the target room
|
|
* Open the `Room settings` screen
|
|
* You might need to click the "info" icon in the top right corner to be able to see the `Room settings` link
|
|
* Navigate to `Advanced` and copy the room id.
|
|
* The format of the room ID is `!<random characters>:example.org`
|
|
|
|
## Usage
|
|
|
|
### Configure GitHub Secrets
|
|
* Open your GitHub repository in your browser
|
|
* Navigate to `Settings`, navigate to `Secrets`
|
|
* Create a new secret by clicking the `New secret` button
|
|
* Name: `MATRIX_TOKEN`
|
|
* Value: Insert the token you copied before. Make sure that there is no newline at the end.
|
|
|
|
### Setup Workflow
|
|
Define a workflow in `.github/workflows/matrix-chat-message.yml` (or add a job if you already have defined workflows).
|
|
|
|
:bulb: Read more about [Configuring a workflow](https://help.github.com/en/articles/configuring-a-workflow).
|
|
|
|
### Example Workflow File
|
|
```yaml
|
|
on: [push]
|
|
|
|
jobs:
|
|
send-message:
|
|
runs-on: ubuntu-latest
|
|
name: Send message via Matrix
|
|
steps:
|
|
- name: Send message to test channel
|
|
id: matrix-chat-message
|
|
uses: fadenb/matrix-chat-message@v0.0.6
|
|
with:
|
|
homeserver: 'matrix.org'
|
|
token: ${{ secrets.MATRIX_TOKEN }}
|
|
channel: '<INSERT YOUR ROOM ID HERE>'
|
|
message: |
|
|
This is an *example message* using **markdown** for formatting.\
|
|
Use a `\` character at the end of a line to cause a linebreak (the whole message is treated as markdown).\
|
|
You can use variables like ${{ github.sha }} anywhere.
|
|
|
|
```
|
|
|
|
* Replace matrix.org with the address of your server.
|
|
* Replace `<INSERT YOUR ROOM ID HERE>` with the room ID you gathered before (it looks like `!nkJduYevFfQSxSMMMP:example.org`).
|
|
* Replace the example message with your own.
|
|
|