Matrix-Chat-Message

What does this action do?

💡 This action can send a message to a Matrix 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 (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).

💡 Read more about Configuring a workflow.

Example Workflow File

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.

fadenb / Matrix-Chat-Message