spantaleev · spantaleev · Nov 8, 2025 · Nov 1, 2025 · Nov 1, 2025 · Nov 1, 2025
diff --git a/.codespellrc b/.codespellrc
@@ -1,2 +1,2 @@
 [codespell]
-ignore-words-list = aNULL,brose,doub,Udo,re-use,re-used,registr
+ignore-words-list = aNULL,brose,doub,Udo,re-use,re-used,registr,shema
diff --git a/README.md b/README.md
@@ -133,6 +133,7 @@ Bridges can be used to connect your Matrix installation with third-party communi
 | [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) | ❌ | Bridge for generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular | [Link](docs/configuring-playbook-bridge-hookshot.md) |
 | [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) | ❌ | Bridge to SMS | [Link](docs/configuring-playbook-bridge-matrix-bridge-sms.md) |
 | [matrix-wechat](https://github.com/duo/matrix-wechat) | ❌ | Bridge to [WeChat](https://www.wechat.com/) | [Link](docs/configuring-playbook-bridge-wechat.md) |
+| [MatrixZulipBridge](https://github.com/GearKite/MatrixZulipBridge) | ❌ | Puppeting appservice bridge for [Zulip](https://zulip.com/) | [Link](docs/configuring-playbook-bridge-zulip.md) |
 | [Heisenbridge](https://github.com/hifi/heisenbridge) | ❌ | Bouncer-style bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) | [Link](docs/configuring-playbook-bridge-heisenbridge.md) |
 | [go-skype-bridge](https://github.com/kelaresg/go-skype-bridge) | ❌ | Bridge to [Skype](https://www.skype.com) | [Link](docs/configuring-playbook-bridge-go-skype-bridge.md) |
 | [mx-puppet-slack](https://gitlab.com/mx-puppet/slack/mx-puppet-slack) | ❌ | Bridge to [Slack](https://slack.com) | [Link](docs/configuring-playbook-bridge-mx-puppet-slack.md) |

diff --git a/docs/configuring-playbook-bridge-zulip.md b/docs/configuring-playbook-bridge-zulip.md
@@ -0,0 +1,78 @@
+<!--
+SPDX-FileCopyrightText: 2021 - 2024 Slavi Pantaleev
+SPDX-FileCopyrightText: 2021 Toni Spets
+SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# Setting up a Zulip bridge (optional)
+
+The playbook can install and configure [MatrixZulipBridge](https://github.com/GearKite/MatrixZulipBridge) for you.
+
+See the project's [documentation](https://github.com/GearKite/MatrixZulipBridge/blob/main/README.md) to learn what it does and why it might be useful to you.
+
+## Adjusting DNS records (optional)
+
+By default, this playbook installs the Zulip bridge on the `matrix.` subdomain, at the `/zulip` path (https://matrix.example.com/zulip). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
+
+If you wish to adjust it, see the section [below](#adjusting-the-zulip-bridge-url-optional) for details about DNS configuration.
+
+## Adjusting the playbook configuration
+
+To enable the Zulip bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
+
+```yaml
+matrix_zulip_bridge_enabled: true
+
+# Setting the owner is optional as the first local user to DM `@matrixzulipbridge:example.com` will be made the owner.
+# If you are not using a local user you must set it as otherwise you can't DM it at all.
+matrix_zulip_bridge_owner: "@alice:{{ matrix_domain }}"
+```
+
+### Adjusting the Zulip bridge URL (optional)
+
+By tweaking the `matrix_zulip_bridge_hostname` and `matrix_zulip_bridge_path_prefix` variables, you can easily make the service available at a **different hostname and/or path** than the default one.
+
+Example additional configuration for your `vars.yml` file:
+
+```yaml
+# Change the default hostname and path prefix
+matrix_zulip_bridge_hostname: zulip.example.com
+matrix_zulip_bridge_path_prefix: /
+```
+
+If you've changed the default hostname, you may need to create a CNAME record for the Zulip bridge domain (`zulip.example.com`), which targets `matrix.example.com`.
+
+When setting, replace `example.com` with your own.
+
+### Extending the configuration
+
+There are some additional things you may wish to configure about the bridge.
+
+Take a look at:
+
+- `roles/custom/matrix-bridge-zulip/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
+
+## Installing
+
+After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
+
+<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
+
+`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
+
+## Usage
+
+To use the bridge, you need to start a chat with `@matrixzulipbridge:example.com` (where `example.com` is your base domain, not the `matrix.` domain). If the bridge ignores you and a DM is not accepted then the owner setting may be wrong.
+
+If you encounter issues or feel lost you can join the project room at [#matrixzulipbridge:shema.lv](https://matrix.to/#/#matrixzulipbridge:shema.lv) for help.
+
+## Troubleshooting
+
+As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-bridge-zulip`.
diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md
@@ -194,6 +194,8 @@ Bridges can be used to connect your Matrix installation with third-party communi
 
 - [Setting up Matrix SMS bridging](configuring-playbook-bridge-matrix-bridge-sms.md)
 
+- [Setting up Zulip bridging](configuring-playbook-bridge-zulip.md)
+
 - [Setting up Heisenbridge bouncer-style IRC bridging](configuring-playbook-bridge-heisenbridge.md)
 
 - [Setting up WeChat bridging](configuring-playbook-bridge-wechat.md)

diff --git a/docs/container-images.md b/docs/container-images.md
@@ -107,6 +107,7 @@ Bridges can be used to connect your Matrix installation with third-party communi
 | [matrix-hookshot](configuring-playbook-bridge-hookshot.md) | [halfshot/matrix-hookshot](https://hub.docker.com/r/halfshot/matrix-hookshot) | ❌ | Bridge for generic webhooks and multiple project management services, such as GitHub, GitLab, Figma, and Jira in particular |
 | [matrix-sms-bridge](configuring-playbook-bridge-matrix-bridge-sms.md) | [folivonet/matrix-sms-bridge](https://hub.docker.com/repository/docker/folivonet/matrix-sms-bridge) | ❌ | Bridge to SMS |
 | [matrix-wechat](configuring-playbook-bridge-wechat.md) | [lxduo/matrix-wechat](https://hub.docker.com/r/lxduo/matrix-wechat) | ❌ | Bridge to [WeChat](https://www.wechat.com/) |
+| [MatrixZulipBridge](configuring-playbook-bridge-zulip.md) | [GearKite/MatrixZulipBridge](https://ghcr.io/gearkite/matrixzulipbridge) | ❌ | Puppeting appservice bridge for [Zulip](https://zulip.com/) |
 | [Heisenbridge](configuring-playbook-bridge-heisenbridge.md) | [hif1/heisenbridge](https://hub.docker.com/r/hif1/heisenbridge) | ❌ | Bouncer-style bridge to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat) |
 | [go-skype-bridge](configuring-playbook-bridge-go-skype-bridge.md) | [nodefyme/go-skype-bridge](https://hub.docker.com/r/nodefyme/go-skype-bridge) | ❌ | Bridge to [Skype](https://www.skype.com) |
 | [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) | [mx-puppet/slack/mx-puppet-slack](https://gitlab.com/mx-puppet/slack/mx-puppet-slack/container_registry) | ❌ | Bridge to [Slack](https://slack.com) |

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
@@ -118,6 +118,8 @@ matrix_homeserver_container_extra_arguments_auto: |
     +
     (['--mount type=bind,src=' + matrix_hookshot_base_path + '/registration.yml,dst=/hookshot-registration.yml,ro'] if matrix_hookshot_enabled else [])
     +
+    (['--mount type=bind,src=' + matrix_zulip_bridge_base_path + '/registration.yaml,dst=/matrixzulipbridge-registration.yaml,ro'] if matrix_zulip_bridge_enabled else [])
+    +
     (['--mount type=bind,src=' + matrix_mautrix_bluesky_config_path + '/registration.yaml,dst=/matrix-mautrix-bluesky-registration.yaml,ro'] if matrix_mautrix_bluesky_enabled else [])
     +
     (['--mount type=bind,src=' + matrix_mautrix_discord_config_path + '/registration.yaml,dst=/matrix-mautrix-discord-registration.yaml,ro'] if matrix_mautrix_discord_enabled else [])
@@ -193,6 +195,8 @@ matrix_homeserver_app_service_config_files_auto: |
     +
     (['/hookshot-registration.yml'] if matrix_hookshot_enabled else [])
     +
+    (['/matrixzulipbridge-registration.yaml'] if matrix_zulip_bridge_enabled else [])
+    +
     (['/matrix-mautrix-bluesky-registration.yaml'] if matrix_mautrix_bluesky_enabled else [])
     +
     (['/matrix-mautrix-discord-registration.yaml'] if matrix_mautrix_discord_enabled else [])
@@ -339,6 +343,8 @@ devture_systemd_service_manager_services_list_auto: |
     +
     ([{'name': 'matrix-hookshot.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'hookshot', 'bridge-hookshot']}] if matrix_hookshot_enabled else [])
     +
+    ([{'name': 'matrix-bridge-zulip.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'matrixzulipbridge']}] if matrix_zulip_bridge_enabled else [])
+    +
     ([{'name': 'matrix-mautrix-bluesky.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'mautrix-bluesky']}] if matrix_mautrix_bluesky_enabled else [])
     +
     ([{'name': 'matrix-mautrix-discord.service', 'priority': 2000, 'groups': ['matrix', 'bridges', 'mautrix-discord']}] if matrix_mautrix_discord_enabled else [])
@@ -2370,6 +2376,51 @@ matrix_hookshot_public_hostname: "{{ matrix_server_fqn_matrix }}"
 #
 ######################################################################
 
+######################################################################
+#
+# matrix-bridge-zulip
+#
+######################################################################
+
+# We don't enable bridges by default.
+matrix_zulip_bridge_enabled: false
+
+matrix_zulip_bridge_scheme: "{{ 'https' if matrix_playbook_ssl_enabled else 'http' }}"
+
+matrix_zulip_bridge_systemd_required_services_list_auto: |
+  {{
+    matrix_addons_homeserver_systemd_services_list
+  }}
+
+matrix_zulip_bridge_docker_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else matrix_zulip_bridge_docker_image_registry_prefix_upstream_default }}"
+
+matrix_zulip_bridge_container_network: "{{ matrix_addons_container_network }}"
+
+matrix_zulip_bridge_container_additional_networks_auto: |-
+  {{
+    (
+      ([] if matrix_addons_homeserver_container_network == '' else [matrix_addons_homeserver_container_network])
+      +
+      [matrix_playbook_reverse_proxyable_services_additional_network] if (matrix_zulip_bridge_container_labels_traefik_enabled and matrix_playbook_reverse_proxyable_services_additional_network) else []
+    ) | unique
+  }}
+
+matrix_zulip_bridge_container_labels_traefik_enabled: "{{ matrix_playbook_reverse_proxy_type in ['playbook-managed-traefik', 'other-traefik-container'] }}"
+matrix_zulip_bridge_container_labels_traefik_docker_network: "{{ matrix_playbook_reverse_proxyable_services_additional_network }}"
+matrix_zulip_bridge_container_labels_traefik_entrypoints: "{{ traefik_entrypoint_primary }}"
+matrix_zulip_bridge_container_labels_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+
+matrix_zulip_bridge_appservice_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'zulip.as.tok', rounds=655555) | to_uuid }}"
+
+matrix_zulip_bridge_homeserver_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'zulip.hs.tok', rounds=655555) | to_uuid }}"
+
+matrix_zulip_bridge_homeserver_url: "{{ matrix_addons_homeserver_client_api_url }}"
+
+######################################################################
+#
+# /matrix-bridge-zulip
+#
+######################################################################
 
 ######################################################################
 #
@@ -5295,6 +5346,11 @@ matrix_synapse_admin_config_asManagedUsers_auto: |
       '^@hbirc_[a-zA-Z0-9]+:'+(matrix_domain | regex_escape)+'$',
     ] if matrix_heisenbridge_enabled else [])
     +
+    ([
+      '^@zulipbot:'+(matrix_domain | regex_escape)+'$',
+      '^@zulip_[a-zA-Z0-9]+:'+(matrix_domain | regex_escape)+'$',
+    ] if matrix_zulip_bridge_enabled else [])
+    +
     ([
       '^@hookshot:'+(matrix_domain | regex_escape)+'$',
       '^@_github_[a-zA-Z0-9]+:'+(matrix_domain | regex_escape)+'$',

diff --git a/roles/custom/matrix-bridge-zulip/defaults/main.yml b/roles/custom/matrix-bridge-zulip/defaults/main.yml
@@ -0,0 +1,125 @@
+# SPDX-FileCopyrightText: 2021 - 2022 Toni Spets
+# SPDX-FileCopyrightText: 2022 - 2023 Nikita Chernyi
+# SPDX-FileCopyrightText: 2022 - 2025 Slavi Pantaleev
+# SPDX-FileCopyrightText: 2022 MDAD project contributors
+# SPDX-FileCopyrightText: 2022 Marko Weltzer
+# SPDX-FileCopyrightText: 2023 Samuel Meenzen
+# SPDX-FileCopyrightText: 2024 - 2025 Suguru Hirahara
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+---
+# MatrixZulipBridge is a puppeting appservice bridge for Zulip
+# Project source code URL: https://github.com/GearKite/MatrixZulipBridge
+
+matrix_zulip_bridge_enabled: true
+
+matrix_zulip_bridge_scheme: https
+matrix_zulip_bridge_hostname: "{{ matrix_server_fqn_matrix }}"
+matrix_zulip_bridge_path_prefix: "/zulip"
+
+# renovate: datasource=docker depName=ghcr.io/gearkite/matrixzulipbridge
+matrix_zulip_bridge_version: v0.4.1
+matrix_zulip_bridge_docker_image: "{{ matrix_zulip_bridge_docker_image_registry_prefix }}gearkite/matrixzulipbridge:{{ matrix_zulip_bridge_version }}"
+matrix_zulip_bridge_docker_image_registry_prefix: "{{ matrix_zulip_bridge_docker_image_registry_prefix_upstream }}"
+matrix_zulip_bridge_docker_image_registry_prefix_upstream: "{{ matrix_zulip_bridge_docker_image_registry_prefix_upstream_default }}"
+matrix_zulip_bridge_docker_image_registry_prefix_upstream_default: ghcr.io/
+matrix_zulip_bridge_docker_image_force_pull: "{{ matrix_zulip_bridge_docker_image.endswith(':latest') }}"
+
+# Set this to your Matrix ID if you want to enforce the owner, otherwise first _local_ user becomes one
+matrix_zulip_bridge_owner: "{{ matrix_admin if matrix_admin else '' }}"
+
+matrix_zulip_bridge_base_path: "{{ matrix_base_data_path }}/zulip"
+
+matrix_zulip_bridge_container_network: ""
+
+# The port number in the container
+matrix_zulip_bridge_container_http_port: 9898
+
+matrix_zulip_bridge_container_additional_networks: "{{ matrix_zulip_bridge_container_additional_networks_auto + matrix_zulip_bridge_container_additional_networks_custom }}"
+matrix_zulip_bridge_container_additional_networks_auto: []
+matrix_zulip_bridge_container_additional_networks_custom: []
+
+# Controls how long to wait for the container to stop gracefully before killing it.
+# We use a small value here, because this container does not seem to handle the SIGTERM signal.
+matrix_zulip_bridge_container_stop_grace_time_seconds: 1
+
+# matrix_zulip_bridge_container_labels_traefik_enabled controls whether labels to assist a Traefik reverse-proxy will be attached to the container.
+# See `../templates/labels.j2` for details.
+#
+# To inject your own other container labels, see `matrix_zulip_bridge_container_labels_additional_labels`.
+matrix_zulip_bridge_container_labels_traefik_enabled: true
+matrix_zulip_bridge_container_labels_traefik_docker_network: "{{ matrix_zulip_bridge_container_network }}"
+matrix_zulip_bridge_container_labels_traefik_hostname: "{{ matrix_zulip_bridge_hostname }}"
+matrix_zulip_bridge_container_labels_traefik_path_prefix: "{{ matrix_zulip_bridge_path_prefix }}"
+matrix_zulip_bridge_container_labels_traefik_entrypoints: web-secure
+matrix_zulip_bridge_container_labels_traefik_tls_certResolver: default  # noqa var-naming
+
+# Controls if the media router is enabled
+matrix_zulip_bridge_container_labels_traefik_media_enabled: true
+matrix_zulip_bridge_container_labels_traefik_media_hostname: "{{ matrix_zulip_bridge_container_labels_traefik_hostname }}"
+# The path prefix must either be `/` or not end with a slash (e.g. `/zulip`).
+matrix_zulip_bridge_container_labels_traefik_media_path_prefix: "{{ '' if matrix_zulip_bridge_container_labels_traefik_path_prefix == '/' else (matrix_zulip_bridge_container_labels_traefik_path_prefix) }}/_bridge_zulip/media"
+matrix_zulip_bridge_container_labels_traefik_media_rule: "Host(`{{ matrix_zulip_bridge_container_labels_traefik_media_hostname }}`){% if matrix_zulip_bridge_container_labels_traefik_media_path_prefix != '/' %} && PathPrefix(`{{ matrix_zulip_bridge_container_labels_traefik_media_path_prefix }}`){% endif %}"
+matrix_zulip_bridge_container_labels_traefik_media_priority: 0
+matrix_zulip_bridge_container_labels_traefik_media_entrypoints: "{{ matrix_zulip_bridge_container_labels_traefik_entrypoints }}"
+matrix_zulip_bridge_container_labels_traefik_media_tls: "{{ matrix_zulip_bridge_container_labels_traefik_media_entrypoints != 'web' }}"
+matrix_zulip_bridge_container_labels_traefik_media_tls_certResolver: "{{ matrix_zulip_bridge_container_labels_traefik_tls_certResolver }}"  # noqa var-naming
+
+# matrix_zulip_bridge_container_labels_additional_labels contains a multiline string with additional labels to add to the container label file.
+# See `../templates/labels.j2` for details.
+#
+# Example:
+# matrix_zulip_bridge_container_labels_additional_labels: |
+#   my.label=1
+#   another.label="here"
+matrix_zulip_bridge_container_labels_additional_labels: ''
+
+# A list of extra arguments to pass to the container
+matrix_zulip_bridge_container_extra_arguments: []
+
+# List of systemd services that service depends on.
+matrix_zulip_bridge_systemd_required_services_list: "{{ matrix_zulip_bridge_systemd_required_services_list_default + matrix_zulip_bridge_systemd_required_services_list_auto + matrix_zulip_bridge_systemd_required_services_list_custom }}"
+matrix_zulip_bridge_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
+matrix_zulip_bridge_systemd_required_services_list_auto: []
+matrix_zulip_bridge_systemd_required_services_list_custom: []
+
+# List of systemd services that service wants
+matrix_zulip_bridge_systemd_wanted_services_list: []
+
+matrix_zulip_bridge_homeserver_url: ""
+
+matrix_zulip_bridge_appservice_token: ''
+matrix_zulip_bridge_homeserver_token: ''
+
+matrix_zulip_bridge_config_media_url: "{{ matrix_zulip_bridge_scheme }}://{{ matrix_zulip_bridge_hostname }}"
+# This matches the hardcoded `DEFAULT_MEDIA_PATH` in MatrixZulipBridge, but uses `matrix_zulip_bridge_path_prefix` as the path prefix.
+# See: https://github.com/GearKite/MatrixZulipBridge/blob/2ba51f3da2ad8bd33460c953ef91a9cfc585a2d4/matrixzulipbridge/__main__.py#L87
+matrix_zulip_bridge_config_media_path: "{{ matrix_zulip_bridge_container_labels_traefik_media_path_prefix }}/v3/download/{netloc}{path}{filename}"
+matrix_zulip_bridge_config_media_key: "{{ matrix_zulip_bridge_homeserver_token }}"
+matrix_zulip_bridge_config_displayname: "MatrixZulipBridge"
+
+matrix_zulip_bridge_registration_yaml_bridge_zulip:
+  media_url: "{{ matrix_zulip_bridge_config_media_url }}"
+  media_path: "{{ matrix_zulip_bridge_config_media_path }}"
+  media_key: "{{ matrix_zulip_bridge_config_media_key }}"
+  displayname: "{{ matrix_zulip_bridge_config_displayname }}"
+
+# Default registration file consumed by both the homeserver and MatrixZulipBridge.
+# Besides registration information, it contains configuration (see the Zulip bridge key).
+matrix_zulip_bridge_registration_yaml:
+  id: zulipbridge
+  url: http://matrix-bridge-zulip:{{ matrix_zulip_bridge_container_http_port }}
+  as_token: "{{ matrix_zulip_bridge_appservice_token }}"
+  hs_token: "{{ matrix_zulip_bridge_homeserver_token }}"
+  rate_limited: false
+  sender_localpart: zulipbridge
+  namespaces:
+    users:
+      - regex: '@zulip_.*'
+        exclusive: true
+    aliases: []
+    rooms: []
+  matrixzulipbridge: "{{ matrix_zulip_bridge_registration_yaml_bridge_zulip }}"
+
+matrix_zulip_bridge_registration: "{{ matrix_zulip_bridge_registration_yaml | from_yaml }}"