{"id":20126452,"url":"https://github.com/sovereigncloudstack/zuul-mqtt-matrix-bridge","last_synced_at":"2026-01-04T15:54:05.223Z","repository":{"id":213451967,"uuid":"707708146","full_name":"SovereignCloudStack/zuul-mqtt-matrix-bridge","owner":"SovereignCloudStack","description":"Relay MQTT reports from Zuul-CI to the Matrix chat","archived":false,"fork":false,"pushed_at":"2024-07-31T19:36:09.000Z","size":52,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-28T01:22:25.211Z","etag":null,"topics":["zuul"],"latest_commit_sha":null,"homepage":"https://zuul.scs.community/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SovereignCloudStack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-20T13:35:55.000Z","updated_at":"2024-07-25T07:46:36.000Z","dependencies_parsed_at":"2024-02-17T20:23:24.789Z","dependency_job_id":"bb0889d9-ba98-4b15-ba13-a6236d63662f","html_url":"https://github.com/SovereignCloudStack/zuul-mqtt-matrix-bridge","commit_stats":null,"previous_names":["sovereigncloudstack/zuul-mqtt-matrix-bridge"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SovereignCloudStack%2Fzuul-mqtt-matrix-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SovereignCloudStack%2Fzuul-mqtt-matrix-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SovereignCloudStack%2Fzuul-mqtt-matrix-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SovereignCloudStack%2Fzuul-mqtt-matrix-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SovereignCloudStack","download_url":"https://codeload.github.com/SovereignCloudStack/zuul-mqtt-matrix-bridge/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245022129,"owners_count":20548486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["zuul"],"created_at":"2024-11-13T20:16:10.198Z","updated_at":"2026-01-04T15:54:05.139Z","avatar_url":"https://github.com/SovereignCloudStack.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# :bridge_at_night: Zuul MQTT reporter -\u003e Matrix chat bridge\n\n[![GitHub Latest Release](https://img.shields.io/github/v/release/SovereignCloudStack/zuul-mqtt-matrix-bridge?logo=github)](https://github.com/SovereignCloudStack/zuul-mqtt-matrix-bridge/releases)\n[![Go Report Card](https://goreportcard.com/badge/github.com/sovereignCloudStack/zuul-mqtt-matrix-bridge)](https://goreportcard.com/report/github.com/sovereignCloudStack/zuul-mqtt-matrix-bridge)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\nRelay MQTT reports from [Zuul-CI](https://zuul-ci.org/) to the [Matrix chat](https://matrix.org/).\n\nCurrently, Zuul-CI has the capability to distribute build reports to various supported platforms\n(refer to the supported drivers [list](https://zuul-ci.org/docs/zuul/latest/drivers/index.html)).\nHowever, there is currently no built-in support for conveniently sending these build reports to the Matrix chat.\n\nThis project offers a straightforward solution for receiving build reports from Zuul's MQTT reporter and,\nusing a predefined template, forwarding these messages to a Matrix chat room.\n\nCurrently, a single instance of \"zuul-mqtt-matrix-bridge\" has the capability to subscribe to multiple MQTT topics.\nHowever, it forwards all messages to just one Matrix room, resulting in an N:1 relationship between MQTT topics\nand Matrix rooms for each \"zuul-mqtt-matrix-bridge\" instance. \n\n![arch](./docs/images/bridge.png)\n\n## Usage\n\nThis section describes a method for integrating the zuul-mqtt-matrix-bridge project into your Zuul-CI infrastructure. It assumes that your Zuul infrastructure is running within Docker containers on the same Docker network. If your setup is different, you can still follow this guide, but make sure that your Zuul deployment can access the MQTT broker container.\n\n### MQTT Broker configuration\n\nThe MQTT broker serves as the backend system responsible for handling messages between the Zuul MQTT client, acting as a publisher, and the zuul-mqtt-matrix-bridge client, acting as a subscriber. The [docker-compose](./docker/docker-compose.yaml) file deploys the Eclipse Mosquitto server, an open-source message broker that utilizes the MQTT protocol.\n\nYou can explore a basic MQTT broker configuration file, [mosquitto.conf](./docker/mosquitto_config/mosquitto.conf), which ensures broker persistence and enforces client authentication via a password file. A password file is a straightforward method for storing usernames and their corresponding encrypted passwords in a single file. Additionally, an example [password file](./docker/mosquitto_config/pwfile) is provided, already containing a user record for the username `mqtt-user` with the password `secret`. You are strongly advised to change these credentials.\n\nIf you need to modify or create an additional password file, please refer to this [guide](https://mosquitto.org/documentation/authentication-methods/).\n\n\n### zuul-mqtt-matrix-bridge configuration\n\nSee the current list of supported configuration options along with their default values:\n\n```text\n  -matrix-homeserver string\n        Matrix homeserver (default \"https://matrix.org\")\n  -matrix-msg-template string\n        Matrix template file (default \"./templates/matrix_message.tmpl\")\n  -matrix-room-id string\n        Matrix room ID\n  -matrix-token string\n        Matrix access token\n  -mqtt-broker string\n        The MQTT Broker (default \"tcp://localhost:1883\")\n  -mqtt-pass string\n        The MQTT password\n  -mqtt-topic string\n        The MQTT topic to subscribe (default \"zuul/#\")\n  -mqtt-topic-qos int\n        The MQTT topic to subscribe\n  -mqtt-user string\n        The MQTT user\n```\n\nAll the configuration options mentioned above can be overridden by environment variables specified in the docker-compose file. You can refer to the [.env](./docker/.env) file for the default values.\n\n### Deployment \n\nIf you intend to connect the zuul-mqtt-matrix-bridge and MQTT broker containers to the pre-existing Zuul-CI Docker networks, ensure that you override the NETWORK_NAME and NETWORK_IS_EXTERNAL variables. Furthermore, remember to override the MATRIX_ROOM_ID and MATRIX_TOKEN variables to guarantee that Zuul reports reach the specific Matrix room of your choice.\n\n1. Clone the repository\n```bash\ngit clone https://github.com/SovereignCloudStack/zuul-mqtt-matrix-bridge.git\n```\n\n2. Deploy zuul-mqtt-matrix-bridge and MQTT broker containers\n```bash\ncd ./zuul-mqtt-matrix-bridge/docker\n\nNETWORK_NAME=\u003czuul-network-name\u003e \\\nNETWORK_IS_EXTERNAL=true \\\nMATRIX_ROOM_ID=\u003ctoken\u003e \\\nMATRIX_TOKEN=\u003croom-id\u003e \\\ndocker-compose up -d\n```\n\n3. Adjust your existing Zuul-CI installation's configuration to establish connectivity with the MQTT broker container. Refer to the relevant Zuul [configuration options](https://zuul-ci.org/docs/zuul/latest/drivers/mqtt.html#connection-configuration) for more details\n\n```bash\n$ cat zuul.conf \n...\n[connection \"mqtt\"]\nname=mqtt\ndriver=mqtt\nserver=mqtt-broker\nport=1883\nuser=mqtt-user\npassword=secret\n...\n```\n\n4. Set up the pipeline to transmit MQTT reports using the connection named as `mqtt`. Refer to the relevant Zuul [configuration options](https://zuul-ci.org/docs/zuul/latest/drivers/mqtt.html#reporter-configuration) for more details.\n\n```yaml\n- pipeline:\n    name: check\n    success:\n      mqtt:\n        topic: \"zuul/{pipeline}/{project}/{branch}/{change}\" # By default, the zuul-mqtt-matrix-bridge subscribes to all topics that have names starting with `zuul` (\"zuul/#\")\n```\n\n## Matrix messages\n\nBy default, Matrix messages are generated using the template file `templates/matrix_message.tmpl`.\nYou have the flexibility to use a custom template file by specifying it with the optional argument \n`-matrix-msg-template`. You are free to utilize any variables defined in Zuul's MQTT reporter message\nschema, which can be found in the Zuul [documentation](https://zuul-ci.org/docs/zuul/latest/drivers/mqtt.html#message-schema) as well as in this project.\n\n### Example messages\n\nThe following examples are generated using the default template file `templates/matrix_message.tmpl`.\n\n\u003chr style=\"width:30%;margin-left:0;\"\u003e\u003c/hr\u003e\n\nℹ️ Starting example jobs.\n\n**Pipeline:** example pipeline\u003cbr\u003e\n**Project:** example/project\u003cbr\u003e\n**Pull request:** [#PR](http://example)\u003cbr\u003e\n**Triggered:** 2000-10-20 09:00:40 +0200 CEST\n\n\u003chr style=\"width:30%;margin-left:0;\"\u003e\u003c/hr\u003e\n\n✅ Build succeeded.\n\n**Pipeline:** example pipeline\u003cbr\u003e\n**Project:** example/project\u003cbr\u003e\n**Pull request:** [#PR](http://example)\u003cbr\u003e\n**Triggered:** 2000-10-20 09:00:40 +0200 CEST\u003cbr\u003e\n**Buildset:** [SUCCESS](http://example/buildset)\u003cbr\u003e\n**Builds:**\n- **example-job-1:** [SUCCESS](http://example/build1)\n  - **Start/End:** 2000-10-20 09:02:40 +0000 UTC -\u003e 2000-10-20 09:03:14 +0000 UTC\n  - _Analyze the related [logs](http://example/logs1)_\n- **example-job-2:** [SUCCESS](http://example/build2)\n  - **Start/End:** 2000-10-20 09:02:40 +0000 UTC -\u003e 2000-10-20 09:03:15 +0000 UTC\n  - _Analyze the related [logs](http://example/logs2)_\n\n\u003chr style=\"width:30%;margin-left:0;\"\u003e\u003c/hr\u003e\n\n⚠️ Build canceled (example pipeline).\n\n**Pipeline:** example pipeline\u003cbr\u003e\n**Project:** example/project\u003cbr\u003e\n**Pull request:** [#PR](http://example)\u003cbr\u003e\n**Triggered:** 2000-10-20 09:00:40 +0200 CEST\n\n\u003chr style=\"width:30%;margin-left:0;\"\u003e\u003c/hr\u003e\n\n❌ Build failed (example pipeline).\n\n**Pipeline:** example pipeline\u003cbr\u003e\n**Project:** example/project\u003cbr\u003e\n**Pull request:** [#PR](http://example)\u003cbr\u003e\n**Triggered:** 2000-10-20 09:00:40 +0200 CEST\u003cbr\u003e\n**Buildset:** [FAILURE](http://example/buildset)\u003cbr\u003e\n**Builds:**\n- **example-job-1:** [SUCCESS](http://example/build1)\n  - **Start/End:** 2000-10-20 09:02:40 +0000 UTC -\u003e 2000-10-20 09:03:14 +0000 UTC\n  - _Analyze the related [logs](http://example/logs1)_\n- **example-job-2:** [FAILURE](http://example/build2)\n  - **Start/End:** 2000-10-20 09:02:40 +0000 UTC -\u003e 2000-10-20 09:03:15 +0000 UTC\n  - _Analyze the related [logs](http://example/logs2)_\n\n\u003chr style=\"width:30%;margin-left:0;\"\u003e\u003c/hr\u003e\n\n## Local development\n\nRefer to the relevant [docs](./docs/local_development.md) section.\n\n## TODOs\n\n- Add unit tests\n- Add TLS support for \"MQTT broker\" \u003c-\u003e \"zuul-mqtt-matrix-bridge\" connection\n\n# Acknowledgment\n\nA portion of bridge code is inspired by @dereisele's project [tuple](https://github.com/dereisele/tuple).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsovereigncloudstack%2Fzuul-mqtt-matrix-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsovereigncloudstack%2Fzuul-mqtt-matrix-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsovereigncloudstack%2Fzuul-mqtt-matrix-bridge/lists"}