Setting Up Matrix Notifications for Your Repository

DRAFT DOCUMENTATION: This documentation is currently in draft form and may not be fully tested and correct. Please verify all procedures before use and report any issues or inaccuracies.

Purpose

This document provides a comprehensive guide for setting up automated Matrix notifications for your Fedora Forge repository using the custom nonbot webhook. This allows you to receive real-time notifications about repository activities directly in your Matrix chat rooms.

Scope

This guide is intended for Fedora Project contributors and repository owners who want to configure automated Matrix notifications for:

  • Issue creation, updates, and closures

  • Pull request events (opened, merged, closed, reviewed)

  • Push events and commits

  • Release notifications

  • Repository events (forks, stars)

Prerequisites

Before setting up Matrix notifications, you need:

  • Repository Access: You must have admin or owner permissions on the repository

  • Matrix Room: A Matrix room where you want to receive notifications

  • Nonbot in your Matrix room the nonbot user needs to be a member of your matrix room. File a ticket on fedora infra to get an admin to add nonbot to your room.

  • Room ID: The internal room ID for your Matrix room (see Obtaining Your Room ID)

Obtaining Your Room ID

To configure the webhook, you need your Matrix room’s internal ID.

  1. Open your Matrix room in Element

  2. Click the room name at the top to open Room Settings

  3. Navigate to Settings → Advanced

  4. Look for Internal room ID (it will look like !BZXFjVQIigxSjizirN:fedora.im)

  5. Copy the entire room ID including the ! and :fedora.im

Setting Up the Nonbot Webhook

Step 1: Navigate to Webhook Settings

  1. Log into Fedora Forge using your Fedora Account

  2. Navigate to your repository

  3. Click on Settings in the repository navigation menu

  4. In the left sidebar, click on Webhooks

  5. Click the Add Webhook button

  6. Select Nonbot from the webhook type dropdown

Step 2: Configure the Webhook

On the webhook configuration page, you’ll need to provide:

Target URL (Matrix Room ID)

Enter your Matrix room ID in the Target URL field:

!abc123xyz:fedora.im

Message Type

Choose the Matrix message type for notifications:

  • Notice (m.notice): Recommended for automated messages. These messages typically won’t trigger notification sounds or badges in Matrix clients.

  • Text (m.text): Regular text messages that will trigger normal notifications. Use this if you want notifications to be more prominent.

Step 3: Select Trigger Events

Choose which repository events should trigger Matrix notifications.

Step 4: Finalize and Test

  1. Review your webhook configuration

  2. Click Add Webhook to save the configuration

  3. The webhook will appear in your webhooks list with a green checkmark if configured correctly

Testing Your Webhook

To verify the webhook is working:

  1. Click on the webhook in the webhooks list

  2. Scroll to the Recent Deliveries section

  3. Click Test Delivery button

  4. Click Test

  5. Check your Matrix room for a test notification

If the test delivery shows a green checkmark, your webhook is configured correctly. If you see a red X, check the delivery details for error information.

Want to help? Learn how to contribute to Fedora Docs ›