Documentation/content/integrations/matrix.md

---
eleventyNavigation:
  key: MatrixIntegration
  title: Integrating with Matrix
  parent: Integrations
---

This article will guide you through integrating Codeberg with Matrix, allowing repo updates to be automatically broadcast
to your project's Matrix room.

## Create a new Matrix account

To set up the Matrix integration, it is recommended that you [create a new account](https://app.element.io/#/register)
dedicated to broadcasting your repo updates. This will act as a bot account.
You can create an account on your preferred Matrix server.

## Getting an access token

You will need an access token to give Codeberg access to send updates from your dedicated Matrix account.
Here's how to do it on the Element web client.

1. Log in to the [Element web client](https://app.element.io/) in a private/incognito browser window, with the Matrix
   account you created earlier.
2. Click on your account name in the top-left corner, then click on `All Settings` in the dropdown.
3. Optionally, you can set a display name and a profile picture for the account here.
4. Navigate to the `Help & About` tab on the left.
5. Scroll to the bottom and click on the `Access Token` dropdown in the advanced section.
6. Copy the access token that appears to a safe place.
7. **Do not log out of Element.** This will invalidate your access token.
   Instead, you can simply close your private/incognito browser.

{% admonition "tip" %}

Alternatively, you can get an access token directly from the Matrix API. Read more at [Matrix's documentation](https://www.matrix.org/docs/guides/client-server-api#login).

{% endadmonition %}

## Connecting your repo to your Matrix using webhooks

Now we will connect the Matrix bot to your Codeberg repository. You will need admin permissions for the repo.

<img src="/images/integrations/matrix/webhooks.png" alt="webhooks">

1. In a web browser, go to your repo and click on the `Settings` button on the top right.
2. Navigate to the `Webhooks` settings tab.
3. Click on the `Add Webhook` button and select `Matrix`.
4. Here are explanations for some key fields:

   - Homeserver URL: for example `https://matrix.org`
   - Room ID: for example `!VTjWrzxSWgLJnHgDUd:matrix.org`.
     You can find this on Element in the `Advanced` tab for the room settings.
   - Access token: type `Bearer <your_access_token>`.
     The access token is the [one you got earlier](#getting-an-access-token).
   - Message type: `m.text` is the most basic type of plaintext message, whereas `m.notice` is intended for bots and
     [behaves slightly differently](https://spec.matrix.org/latest/client-server-api/#mnotice).

Add your webhook, then click on the webhook URL. At the bottom now, there will be a `Test Delivery` button.
Click this, and you will receive a message on your Matrix room!