Merge pull request #1505 from HarHarLinks/hookshot

add matrix-hookshot

docs/configuring-playbook-bridge-hookshot.md

@@ -0,0 +1,44 @@
+# Setting up Hookshot (optional)
+
+The playbook can install and configure [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) for you.
+
+See the project's [documentation](https://half-shot.github.io/matrix-hookshot/hookshot.html) to learn what it does and why it might be useful to you.
+
+
+## Setup Instructions
+
+Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/setup.html) to learn what the individual options do.
+
+1. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml) as required.
+2. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma).
+3. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-matrix-aux-role) explained below. 
+4. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`.
+5. Refer to [Hookshot's official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge. Note that the different listeners are bound to certain paths (see `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/matrix-bridge-hookshot/tasks/init.yml)): by default webhooks root is `/hookshot/webhooks/`.
+
+Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml) for how to use them.
+
+### Manage GitHub Private Key with matrix-aux role
+
+The GitHub bridge requires you to install a private key file. This can be done in multiple ways:
+- copy the *contents* of the downloaded file and set the variable `matrix_hookshot_github_private_key` to the contents (see example in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml)).
+- somehow copy the file to the path `{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}` (default: `/matrix/hookshot/private-key.pem`) on the server manually.
+- use the `matrix-aux` role to copy the file from an arbitrary path on your ansible client to the correct path on the server.
+
+To use `matrix-aux`, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add to `matrix-aux` configuration like this:
+```yaml
+matrix_aux_file_definitions:
+  - dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
+    content: "{{ lookup('file', '/path/to/your-github-private-key.pem') }}"
+    mode: '0400'
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+```
+For more info see the documentation in the [matrix-aux base configuration file](/roles/matrix-aux/defaults/main.yml).
+
+### Provisioning API
+
+The provisioning API will be enabled automatically if you set `matrix_dimension_enabled: true` and provided a `matrix_hookshot_provisioning_secret`, unless you override it either way. To use hookshot with dimension, you will need to enter as "Provisioning URL": `http://matrix-hookshot:9002`, which is made up of the variables `matrix_hookshot_container_url` and `matrix_hookshot_provisioning_port`.
+
+### Metrics
+
+If metrics are enabled, they will be automatically available in the builtin Prometheus and Grafana, but you need to set up your own Dashboard for now. If additionally metrics proxying for use with external Prometheus is enabled (`matrix_nginx_proxy_proxy_synapse_metrics`), hookshot metrics will also be available (at `matrix_hookshot_metrics_endpoint`, default `/hookshot/metrics`, on the stats subdomain) and with the same password. See also [the Prometheus and Grafana docs](../configuring-playbook-prometheus-grafana.md).

group_vars/matrix_servers

@@ -662,6 +662,45 @@ matrix_heisenbridge_systemd_wanted_services_list: |
 #
 ######################################################################
 
+######################################################################
+#
+# matrix-bridge-hookshot
+#
+######################################################################
+
+# We don't enable bridges by default.
+matrix_hookshot_enabled: false
+
+matrix_hookshot_appservice_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'hookshot.as.tok') | to_uuid }}"
+
+matrix_hookshot_homeserver_token: "{{ '%s' | format(matrix_homeserver_generic_secret_key) | password_hash('sha512', 'hookshot.hs.tok') | to_uuid }}"
+
+matrix_hookshot_systemd_wanted_services_list: |
+  {{
+    (['matrix-' + matrix_homeserver_implementation + '.service'])
+    +
+    (['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
+  }}
+
+matrix_hookshot_container_http_host_bind_ports_defaultmapping:
+  - "127.0.0.1:{{ matrix_hookshot_appservice_port }}:{{ matrix_hookshot_appservice_port }}"
+  - "127.0.0.1:{{ matrix_hookshot_metrics_port }}:{{ matrix_hookshot_metrics_port }}"
+  - "127.0.0.1:{{ matrix_hookshot_webhook_port }}:{{ matrix_hookshot_webhook_port }}"
+  - "127.0.0.1:{{ matrix_hookshot_provisioning_port }}:{{ matrix_hookshot_provisioning_port }}"
+
+matrix_hookshot_container_http_host_bind_ports: "{{ [] if matrix_nginx_proxy_enabled else matrix_hookshot_container_http_host_bind_ports_defaultmapping }}"
+
+matrix_hookshot_provisioning_enabled: "{{ matrix_hookshot_provisioning_secret and matrix_dimension_enabled }}"
+
+matrix_hookshot_proxy_metrics: "{{ matrix_nginx_proxy_proxy_synapse_metrics }}"
+matrix_hookshot_proxy_metrics_basic_auth_enabled: "{{ matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_enabled }}"
+
+######################################################################
+#
+# /matrix-bridge-hookshot
+#
+######################################################################
+
 ######################################################################
 #
 # matrix-bridge-mx-puppet-skype
@@ -1484,6 +1523,8 @@ matrix_nginx_proxy_systemd_wanted_services_list: |
     (['matrix-bot-go-neb.service'] if matrix_bot_go_neb_enabled else [])
     +
     (['matrix-etherpad.service'] if matrix_etherpad_enabled and matrix_dimension_enabled else [])
+    +
+    (['matrix-hookshot.service'] if matrix_hookshot_enabled else [])
   }}
 
 matrix_ssl_domains_to_obtain_certificates_for: |
@@ -2095,6 +2136,8 @@ matrix_prometheus_scraper_node_targets: "{{ ['matrix-prometheus-node-exporter:91
 matrix_prometheus_scraper_postgres_enabled: "{{ matrix_prometheus_postgres_exporter_enabled }}"
 matrix_prometheus_scraper_postgres_targets: "{{ ['matrix-prometheus-postgres-exporter:'+ matrix_prometheus_postgres_exporter_port|string] if matrix_prometheus_scraper_postgres_enabled else [] }}"
 
+matrix_prometheus_scraper_hookshot_enabled: "{{ matrix_hookshot_metrics_enabled }}"
+matrix_prometheus_scraper_hookshot_targets: "{{ [matrix_hookshot_container_url|string +':'+ matrix_hookshot_metrics_port|string] if matrix_hookshot_metrics_enabled else [] }}"
 
 ######################################################################
 #

roles/matrix-bridge-hookshot/defaults/main.yml

@@ -0,0 +1,201 @@
+# A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA.
+# https://github.com/Half-Shot/matrix-hookshot
+
+matrix_hookshot_enabled: true
+
+matrix_hookshot_version: 1.1.0
+matrix_hookshot_docker_image: "{{ matrix_container_global_registry_prefix }}halfshot/matrix-hookshot:{{ matrix_hookshot_version }}"
+matrix_hookshot_docker_image_force_pull: "{{ matrix_hookshot_docker_image.endswith(':latest') }}"
+
+matrix_hookshot_base_path: "{{ matrix_base_data_path }}/hookshot"
+
+matrix_hookshot_homeserver_address: "{{ matrix_homeserver_container_url }}"
+matrix_hookshot_container_url: 'matrix-hookshot'
+
+matrix_hookshot_public_endpoint: /hookshot
+
+# There is no need to edit ports. use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
+matrix_hookshot_appservice_port: 9993
+matrix_hookshot_appservice_endpoint: "{{ matrix_hookshot_public_endpoint }}/_matrix/app"
+
+# Metrics work only in conjunction with matrix_synapse_metrics_enabled etc
+matrix_hookshot_metrics_enabled: true
+# There is no need to edit ports.
+# Read the documentation to learn about using hookshot metrics with external Prometheus
+# If you still want something different, use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
+matrix_hookshot_metrics_port: 9001
+matrix_hookshot_metrics_endpoint: "{{ matrix_hookshot_public_endpoint }}/metrics"
+
+# There is no need to edit ports. use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
+matrix_hookshot_webhook_port: 9000
+matrix_hookshot_webhook_endpoint: "{{ matrix_hookshot_public_endpoint }}/webhooks"
+
+
+# You need to create a GitHub app to enable this and fill in the empty variables below
+# https://half-shot.github.io/matrix-hookshot/setup/github.html
+matrix_hookshot_github_enabled: false
+matrix_hookshot_github_appid: ''
+# Set this variable to the contents of the generated and downloaded GitHub private key:
+# matrix_hookshot_github_private_key: |
+#   -----BEGIN RSA PRIVATE KEY-----
+#   0123456789ABCDEF...
+#   -----END RSA PRIVATE KEY-----
+# Alternatively, leave it empty and do it manually or use matrix-aux instead, see docs/matrix-bridge-hookshot.md for info.
+matrix_hookshot_github_private_key: ''
+matrix_hookshot_github_private_key_file: 'private-key.pem'
+matrix_hookshot_github_secret: '' # "Webhook secret" on the GitHub App page
+matrix_hookshot_github_oauth_enabled: false
+# You need to configure oauth settings only when you have enabled oauth (optional)
+matrix_hookshot_github_oauth_id: '' # "Client ID" on the GitHub App page
+matrix_hookshot_github_oauth_secret: '' # "Client Secret" on the GitHub App page
+# Default value of matrix_hookshot_github_oauth_endpoint: "/hookshot/webhooks/oauth"
+matrix_hookshot_github_oauth_endpoint: "{{ matrix_hookshot_webhook_endpoint }}/oauth"
+matrix_hookshot_github_oauth_uri: "https://{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_github_oauth_endpoint }}"
+# These are the default settings mentioned here and don't need to be modified: https://half-shot.github.io/matrix-hookshot/usage/room_configuration/github_repo.html#configuration
+matrix_hookshot_github_ignore_hooks: "{}"
+matrix_hookshot_github_command_prefix: '!gh'
+matrix_hookshot_github_show_issue_room_link: false
+matrix_hookshot_github_pr_diff: "{enabled: false, maxLines: 5}"
+matrix_hookshot_github_including_labels: ''
+matrix_hookshot_github_excluding_labels: ''
+
+
+matrix_hookshot_gitlab_enabled: true
+# Optionally add your instances, e.g.
+# matrix_hookshot_gitlab_instances:
+#   gitlab.com:
+#     url: https://gitlab.com
+#   mygitlab:
+#     url: https://gitlab.example.org
+matrix_hookshot_gitlab_instances:
+  gitlab.com:
+    url: https://gitlab.com
+
+# This will be the "Secret token" you have to enter into all GitLab instances for authentication
+matrix_hookshot_gitlab_secret: ''
+
+
+matrix_hookshot_jira_enabled: false
+# Get the these values from https://half-shot.github.io/matrix-hookshot/setup/jira.html#jira-oauth
+matrix_hookshot_jira_secret: ''
+matrix_hookshot_jira_oauth_enabled: false
+matrix_hookshot_jira_oauth_id: ''
+matrix_hookshot_jira_oauth_secret: ''
+# Default value of matrix_hookshot_jira_oauth_endpoint: "/hookshot/webhooks/jira/oauth"
+matrix_hookshot_jira_oauth_endpoint: "{{ matrix_hookshot_webhook_endpoint }}/jira/oauth"
+matrix_hookshot_jira_oauth_uri: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_jira_oauth_endpoint }}"
+
+
+# No need to change these
+matrix_hookshot_generic_enabled: true
+# Default value of matrix_hookshot_generic_endpoint: "/hookshot/webhooks"
+matrix_hookshot_generic_endpoint: "{{ matrix_hookshot_webhook_endpoint }}"
+matrix_hookshot_generic_urlprefix: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_generic_endpoint }}"
+matrix_hookshot_generic_allow_js_transformation_functions: false
+# If you're also using matrix-appservice-webhooks, take care that these prefixes don't overlap
+matrix_hookshot_generic_user_id_prefix: '_webhooks_'
+
+
+matrix_hookshot_figma_enabled: false
+# Default value of matrix_hookshot_figma_endpoint: "/hookshot/webhooks/figma/webhook"
+matrix_hookshot_figma_endpoint: "{{ matrix_hookshot_webhook_endpoint }}/figma/webhook"
+matrix_hookshot_figma_publicUrl: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_figma_endpoint }}"
+# To bridge figma webhooks, you need to configure one of multiple instances like this:
+# matrix_hookshot_figma_instances:
+#   your-instance:
+#       teamId: your-team-id
+#       accessToken: your-personal-access-token
+#       passcode: your-webhook-passcode
+
+
+# There is no need to edit ports. use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
+matrix_hookshot_provisioning_port: 9002
+matrix_hookshot_provisioning_secret: ''
+# Provisioning will be automatically enabled if dimension is enabled and you have provided a provisioning secret, unless you override it
+matrix_hookshot_provisioning_enabled: false
+matrix_hookshot_provisioning_endpoint: "{{ matrix_hookshot_public_endpoint }}/v1"
+
+# You can configure access to the bridge as documented here https://half-shot.github.io/matrix-hookshot/setup.html#permissions
+# When empty, the default permissions are applied.
+# Example:
+# matrix_hookshot_permissions:
+#   - actor: *
+#     services:
+#       - service: *
+#         level: commands
+#   - actor: example.com
+#     services:
+#       - service: "*"
+#         level: admin
+matrix_hookshot_permissions: []
+
+matrix_hookshot_bot_displayname: Hookshot Bot
+matrix_hookshot_bot_avatar: 'mxc://half-shot.uk/2876e89ccade4cb615e210c458e2a7a6883fe17d'
+
+# A list of extra arguments to pass to the container
+matrix_hookshot_container_extra_arguments: []
+
+# List of systemd services that service depends on.
+matrix_hookshot_systemd_required_services_list: ['docker.service']
+
+# List of systemd services that service wants
+matrix_hookshot_systemd_wanted_services_list: []
+
+# List of ports to bind to the host to expose them directly.
+# Ports will automatically be bound to localhost if matrix_nginx_proxy_enabled is false.
+# Setting this variable will override that behaviour in either case.
+# Supply docker port bind arguments in a list like this:
+#
+# matrix_hookshot_container_http_host_bind_ports:
+#   - "127.0.0.1:9999:{{ matrix_hookshot_metrics_port }}"
+#
+# Above example will bind the metrics port in the container to port 9999 on localhost.
+matrix_hookshot_container_http_host_bind_ports: []
+
+# These tokens will be set automatically
+matrix_hookshot_appservice_token: ''
+matrix_hookshot_homeserver_token: ''
+
+# Default configuration template which covers the generic use case.
+# You can customize it by controlling the various variables inside it.
+#
+# For a more advanced customization, you can extend the default (see `matrixhookshot_configuration_extension_yaml`)
+# or completely replace this variable with your own template.
+matrix_hookshot_configuration_yaml: "{{ lookup('template', 'templates/config.yml.j2') }}"
+
+matrix_hookshot_configuration_extension_yaml: |
+  # Your custom YAML configuration goes here.
+  # This configuration extends the default starting configuration (`matrix_hookshot_configuration_yaml`).
+  #
+  # You can override individual variables from the default configuration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_hookshot_configuration_yaml`.
+
+matrix_hookshot_configuration_extension: "{{ matrix_hookshot_configuration_extension_yaml|from_yaml if matrix_hookshot_configuration_extension_yaml|from_yaml is mapping else {} }}"
+
+# Holds the final configuration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_hookshot_configuration_yaml`.
+matrix_hookshot_configuration: "{{ matrix_hookshot_configuration_yaml|from_yaml|combine(matrix_hookshot_configuration_extension, recursive=True) }}"
+
+# Default registration template which covers the generic use case.
+# You can customize it by controlling the various variables inside it.
+#
+# For a more advanced customization, you can extend the default (see `matrixhookshot_registration_extension_yaml`)
+# or completely replace this variable with your own template.
+matrix_hookshot_registration_yaml: "{{ lookup('template', 'templates/registration.yml.j2') }}"
+
+matrix_hookshot_registration_extension_yaml: |
+  # Your custom YAML registration goes here.
+  # This registration extends the default starting registration (`matrix_hookshot_registration_yaml`).
+  #
+  # You can override individual variables from the default registration, or introduce new ones.
+  #
+  # If you need something more special, you can take full control by
+  # completely redefining `matrix_hookshot_registration_yaml`.
+
+matrix_hookshot_registration_extension: "{{ matrix_hookshot_registration_extension_yaml|from_yaml if matrix_hookshot_registration_extension_yaml|from_yaml is mapping else {} }}"
+
+# Holds the final registration (a combination of the default and its extension).
+# You most likely don't need to touch this variable. Instead, see `matrix_hookshot_registration_yaml`.
+matrix_hookshot_registration: "{{ matrix_hookshot_registration_yaml|from_yaml|combine(matrix_hookshot_registration_extension, recursive=True) }}"

roles/matrix-bridge-hookshot/tasks/init.yml

@@ -0,0 +1,129 @@
+# If the matrix-synapse role is not used, `matrix_synapse_role_executed` won't exist.
+# We don't want to fail in such cases.
+- name: Fail if matrix-synapse role already executed
+  fail:
+    msg: >-
+      The matrix-bridge-hookshot role needs to execute before the matrix-synapse role.
+  when: "matrix_hookshot_enabled and matrix_synapse_role_executed|default(False)"
+
+- set_fact:
+    matrix_systemd_services_list: "{{ matrix_systemd_services_list + ['matrix-hookshot.service'] }}"
+  when: matrix_hookshot_enabled|bool
+
+# If the matrix-synapse role is not used, these variables may not exist.
+- set_fact:
+    matrix_synapse_container_extra_arguments: >
+      {{ matrix_synapse_container_extra_arguments|default([]) }}
+      +
+      ["--mount type=bind,src={{ matrix_hookshot_base_path }}/registration.yml,dst=/hookshot-registration.yml,ro"]
+
+    matrix_synapse_app_service_config_files: >
+      {{ matrix_synapse_app_service_config_files|default([]) }}
+      +
+      {{ ["/hookshot-registration.yml"] }}
+  when: matrix_hookshot_enabled|bool
+
+- block:
+  - name: Fail if matrix-nginx-proxy role already executed
+    fail:
+      msg: >-
+        Trying to append hookshot's reverse-proxying configuration to matrix-nginx-proxy,
+        but it's pointless since the matrix-nginx-proxy role had already executed.
+        To fix this, please change the order of roles in your playbook,
+        so that the matrix-nginx-proxy role would run after the matrix-bridge-hookshot role.
+    when: matrix_nginx_proxy_role_executed|default(False)|bool
+
+  - name: Generate Matrix hookshot proxying configuration for matrix-nginx-proxy
+    set_fact:
+      matrix_hookshot_matrix_nginx_proxy_configuration: |
+        location ~ ^{{ matrix_hookshot_appservice_endpoint }}/(.*)$ {
+          {% if matrix_nginx_proxy_enabled|default(False) %}
+            {# Use the embedded DNS resolver in Docker containers to discover the service #}
+            resolver 127.0.0.11 valid=5s;
+            set $backend "{{ matrix_hookshot_container_url }}:{{ matrix_hookshot_appservice_port }}";
+            proxy_pass http://$backend/$1;
+          {% else %}
+            {# Generic configuration for use outside of our container setup #}
+            proxy_pass http://127.0.0.1:{{ matrix_hookshot_appservice_port }}/$1;
+          {% endif %}
+          proxy_set_header Host $host;
+        }
+        {% if matrix_hookshot_provisioning_enabled %}
+        location ~ ^{{ matrix_hookshot_provisioning_endpoint }}/(.*)$ {
+          {% if matrix_nginx_proxy_enabled|default(False) %}
+            {# Use the embedded DNS resolver in Docker containers to discover the service #}
+            resolver 127.0.0.11 valid=5s;
+            set $backend "{{ matrix_hookshot_container_url }}:{{ matrix_hookshot_provisioning_port }}";
+            proxy_pass http://$backend/$1;
+          {% else %}
+            {# Generic configuration for use outside of our container setup #}
+            proxy_pass http://127.0.0.1:{{ matrix_hookshot_provisioning_port }}/$1;
+          {% endif %}
+          proxy_set_header Host $host;
+        }
+        {% endif %}
+        location ~ ^{{ matrix_hookshot_webhook_endpoint }}/(.*)$ {
+          {% if matrix_nginx_proxy_enabled|default(False) %}
+            {# Use the embedded DNS resolver in Docker containers to discover the service #}
+            resolver 127.0.0.11 valid=5s;
+            set $backend "{{ matrix_hookshot_container_url }}:{{ matrix_hookshot_webhook_port }}";
+            proxy_pass http://$backend/$1;
+          {% else %}
+            {# Generic configuration for use outside of our container setup #}
+            proxy_pass http://127.0.0.1:{{ matrix_hookshot_webhook_port }}/$1;
+          {% endif %}
+          proxy_set_header Host $host;
+        }
+
+  - name: Register hookshot proxying configuration with matrix-nginx-proxy
+    set_fact:
+      matrix_nginx_proxy_proxy_matrix_additional_server_configuration_blocks: |
+        {{
+          matrix_nginx_proxy_proxy_matrix_additional_server_configuration_blocks|default([])
+          +
+          [matrix_hookshot_matrix_nginx_proxy_configuration]
+        }}
+
+  - name: Generate Matrix hookshot proxying configuration for matrix-nginx-proxy
+    set_fact:
+      matrix_hookshot_matrix_nginx_proxy_metrics_configuration: |
+        {% if matrix_hookshot_metrics_enabled and matrix_hookshot_proxy_metrics %}
+        location {{ matrix_hookshot_metrics_endpoint }} {
+          {% if matrix_nginx_proxy_enabled|default(False) %}
+            {# Use the embedded DNS resolver in Docker containers to discover the service #}
+            resolver 127.0.0.11 valid=5s;
+            set $backend "{{ matrix_hookshot_container_url }}:{{ matrix_hookshot_metrics_port }}";
+            proxy_pass http://$backend/metrics;
+          {% else %}
+            {# Generic configuration for use outside of our container setup #}
+            proxy_pass http://127.0.0.1:{{ matrix_hookshot_metrics_port }}/metrics;
+          {% endif %}
+          proxy_set_header Host $host;
+          {% if matrix_hookshot_proxy_metrics_basic_auth_enabled %}
+            auth_basic "protected";
+            auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
+          {% endif %}
+        }
+        {% endif %}
+
+  - name: Register hookshot metrics proxying configuration with matrix-nginx-proxy
+    set_fact:
+      matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks: |
+        {{
+          matrix_nginx_proxy_proxy_grafana_additional_server_configuration_blocks|default([])
+          +
+          [matrix_hookshot_matrix_nginx_proxy_metrics_configuration]
+        }}
+  tags:
+   - always
+  when: matrix_hookshot_enabled|bool
+
+- name: Warn about reverse-proxying if matrix-nginx-proxy not used
+  debug:
+    msg: >-
+      NOTE: You've enabled the hookshot bridge but are not using the matrix-nginx-proxy
+      reverse proxy.
+      Please make sure that you're proxying the `{{ matrix_hookshot_public_endpoint }}`
+      URL endpoint to the matrix-hookshot container.
+      You can expose the container's ports using the `matrix_hookshot_container_http_host_bind_ports` variable.
+  when: "matrix_hookshot_enabled|bool and matrix_nginx_proxy_enabled is not defined"

roles/matrix-bridge-hookshot/tasks/main.yml

@@ -0,0 +1,21 @@
+- import_tasks: "{{ role_path }}/tasks/init.yml"
+  tags:
+    - always
+
+- import_tasks: "{{ role_path }}/tasks/validate_config.yml"
+  when: "run_setup|bool and matrix_hookshot_enabled|bool"
+  tags:
+    - setup-all
+    - setup-hookshot
+
+- import_tasks: "{{ role_path }}/tasks/setup_install.yml"
+  when: "run_setup|bool and matrix_hookshot_enabled|bool"
+  tags:
+    - setup-all
+    - setup-hookshot
+
+- import_tasks: "{{ role_path }}/tasks/setup_uninstall.yml"
+  when: "run_setup|bool and not matrix_hookshot_enabled|bool"
+  tags:
+    - setup-all
+    - setup-hookshot

roles/matrix-bridge-hookshot/tasks/setup_install.yml

@@ -0,0 +1,84 @@
+---
+
+- import_tasks: "{{ role_path }}/../matrix-base/tasks/util/ensure_openssl_installed.yml"
+
+- name: Ensure hookshot image is pulled
+  docker_image:
+    name: "{{ matrix_hookshot_docker_image }}"
+    source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
+    force_source: "{{ matrix_hookshot_docker_image_force_pull if ansible_version.major > 2 or ansible_version.minor >= 8 else omit }}"
+    force: "{{ omit if ansible_version.major > 2 or ansible_version.minor >= 8 else matrix_hookshot_docker_image_force_pull }}"
+
+- name: Ensure hookshot paths exist
+  file:
+    path: "{{ item }}"
+    state: directory
+    mode: 0750
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  with_items:
+    - "{{ matrix_hookshot_base_path }}"
+
+- name: Check if hookshot passkey exists
+  stat:
+    path: "{{ matrix_hookshot_base_path }}/passkey.pem"
+  register: hookshot_passkey_file
+
+- name: Generate hookshot passkey if it doesn't exist
+  shell: "{{ matrix_host_command_openssl }} genpkey -out {{ matrix_hookshot_base_path }}/passkey.pem -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:4096"
+  become: true
+  become_user: "{{ matrix_user_username }}"
+  when: "not hookshot_passkey_file.stat.exists"
+
+- name: Ensure hookshot config.yml installed if provided
+  copy:
+    content: "{{ matrix_hookshot_configuration|to_nice_yaml }}"
+    dest: "{{ matrix_hookshot_base_path }}/config.yml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
+- name: Validate hookshot config.yml
+  command: |
+    {{ matrix_host_command_docker }} run
+    --rm
+    --name={{ matrix_hookshot_container_url }}-validate
+    --user={{ matrix_user_uid }}:{{ matrix_user_gid }}
+    --cap-drop=ALL
+    -v {{ matrix_hookshot_base_path }}/config.yml:/config.yml
+    {{ matrix_hookshot_docker_image }} node Config/Config.js /config.yml
+  register: hookshot_config_validation_result
+
+- name: Fail if hookshot config.yml invalid
+  fail:
+    msg: "Your hookshot configuration did not pass validation:\n{{ hookshot_config_validation_result.stdout }}\n{{ hookshot_config_validation_result.stderr }}"
+  when: "hookshot_config_validation_result.rc > 0"
+
+- name: Ensure hookshot registration.yml installed if provided
+  copy:
+    content: "{{ matrix_hookshot_registration|to_nice_yaml }}"
+    dest: "{{ matrix_hookshot_base_path }}/registration.yml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
+- name: Ensure hookshot github private key file installed if github is enabled
+  copy:
+    content: "{{ matrix_hookshot_github_private_key }}"
+    dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
+    mode: 0400
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+  when: "{{ matrix_hookshot_github_enabled|bool and matrix_hookshot_github_private_key|length }}"
+
+- name: Ensure matrix-hookshot.service installed
+  template:
+    src: "{{ role_path }}/templates/systemd/matrix-hookshot.service.j2"
+    dest: "{{ matrix_systemd_path }}/matrix-hookshot.service"
+    mode: 0644
+  register: matrix_hookshot_systemd_service_result
+
+- name: Ensure systemd reloaded after matrix-hookshot.service installation
+  service:
+    daemon_reload: yes
+  when: matrix_hookshot_systemd_service_result.changed

roles/matrix-bridge-hookshot/tasks/setup_uninstall.yml

@@ -0,0 +1,25 @@
+---
+
+- name: Check existence of matrix-hookshot service
+  stat:
+    path: "{{ matrix_systemd_path }}/matrix-hookshot.service"
+  register: matrix_hookshot_service_stat
+
+- name: Ensure matrix-hookshot is stopped
+  service:
+    name: matrix-hookshot
+    state: stopped
+    enabled: no
+    daemon_reload: yes
+  when: "matrix_hookshot_service_stat.stat.exists"
+
+- name: Ensure matrix-hookshot.service doesn't exist
+  file:
+    path: "{{ matrix_systemd_path }}/matrix-hookshot.service"
+    state: absent
+  when: "matrix_hookshot_service_stat.stat.exists"
+
+- name: Ensure systemd reloaded after matrix-hookshot.service removal
+  service:
+    daemon_reload: yes
+  when: "matrix_hookshot_service_stat.stat.exists"

roles/matrix-bridge-hookshot/tasks/validate_config.yml

@@ -0,0 +1,59 @@
+---
+
+- name: Fail if required settings not defined
+  fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item }}`).
+  when: "vars[item] == ''"
+  with_items:
+    - "matrix_hookshot_appservice_token"
+    - "matrix_hookshot_homeserver_token"
+
+- name: Fail if required GitHub settings not defined
+  fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item }}`) to enable GitHub.
+  when: "matrix_hookshot_github_enabled and vars[item] == ''"
+  with_items:
+    - "matrix_hookshot_github_appid"
+    - "matrix_hookshot_github_secret"
+
+- name: Fail if required GitHub OAuth settings not defined
+  fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item }}`) to enable GitHub OAuth.
+  when: "matrix_hookshot_github_oauth_enabled and vars[item] == ''"
+  with_items:
+    - "matrix_hookshot_github_oauth_id"
+    - "matrix_hookshot_github_oauth_secret"
+
+- name: Fail if required Jira settings not defined
+  fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item }}`) to enable Jira.
+  when: "matrix_hookshot_jira_enabled and vars[item] == ''"
+  with_items:
+    - "matrix_hookshot_jira_secret"
+
+- name: Fail if required Jira OAuth settings not defined
+  fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item }}`) to enable Jira OAuth.
+  when: "matrix_hookshot_jira_oauth_enabled and vars[item] == ''"
+  with_items:
+    - "matrix_hookshot_jira_oauth_id"
+    - "matrix_hookshot_jira_oauth_secret"
+
+- name: Fail if required Figma settings not defined
+  fail:
+    msg: >-
+      You need to define at least one Figma instance to enable Figma.
+  when: "matrix_hookshot_figma_enabled and matrix_hookshot_figma_instances is undefined"
+
+- name: Fail if required provisioning settings not defined
+  fail:
+    msg: >-
+      You need to define a required configuration setting (`{{ item }}`) to enable provisioning.
+  when: "matrix_hookshot_provisioning_enabled and vars[item] == ''"
+  with_items:
+    - "matrix_hookshot_provisioning_secret"

roles/matrix-bridge-hookshot/templates/config.yml.j2

@@ -0,0 +1,127 @@
+#jinja2: lstrip_blocks: "True"
+bridge:
+  # Basic homeserver configuration
+  #
+  domain: {{ matrix_domain }}
+  url: {{ matrix_hookshot_homeserver_address }}
+  mediaUrl: {{ matrix_hookshot_homeserver_address }}
+  port: {{ matrix_hookshot_appservice_port }}
+  bindAddress: 0.0.0.0
+{% if matrix_hookshot_github_enabled %}
+github:
+  # (Optional) Configure this to enable GitHub support
+  #
+  auth:
+    # Authentication for the GitHub App.
+    #
+    id: {{ matrix_hookshot_github_appid }}
+    privateKeyFile: /data/{{ matrix_hookshot_github_private_key_file }}
+  webhook:
+    # Webhook settings for the GitHub app.
+    #
+    secret: {{ matrix_hookshot_github_secret|to_json }}
+{% if matrix_hookshot_github_oauth_enabled %}
+  oauth:
+    # (Optional) Settings for allowing users to sign in via OAuth.
+    #
+    client_id: {{ matrix_hookshot_github_oauth_id }}
+    client_secret: {{ matrix_hookshot_github_oauth_secret|to_json }}
+    redirect_uri: {{ matrix_hookshot_github_oauth_uri }}
+{% endif %}
+  defaultOptions:
+    # (Optional) Default options for GitHub connections.
+    #
+    ignoreHooks: {{ matrix_hookshot_github_ignore_hooks }}
+    commandPrefix: "{{ matrix_hookshot_github_command_prefix }}"
+    showIssueRoomLink: {{ matrix_hookshot_github_show_issue_room_link }}
+    prDiff: {{ matrix_hookshot_github_pr_diff }}
+    includingLabels:{{ matrix_hookshot_github_including_labels }}
+    excludingLabels: {{ matrix_hookshot_github_excluding_labels }}
+{% endif %}
+{% if matrix_hookshot_gitlab_enabled %}
+gitlab:
+  # (Optional) Configure this to enable GitLab support
+  #
+  instances:
+    {{ matrix_hookshot_gitlab_instances }}
+  webhook:
+    secret: {{ matrix_hookshot_gitlab_secret|to_json }}
+{% endif %}
+{% if matrix_hookshot_jira_enabled %}
+jira:
+  # (Optional) Configure this to enable Jira support
+  #
+  webhook:
+    secret: {{ matrix_hookshot_jira_secret|to_json }}
+{% if matrix_hookshot_jira_oauth_enabled %}
+  oauth:
+    client_id: {{ matrix_hookshot_jira_oauth_id|to_json }}
+    client_secret: {{ matrix_hookshot_jira_oauth_secret|to_json }}
+    redirect_uri: {{ matrix_hookshot_jira_oauth_uri }}
+{% endif %}
+{% endif %}
+{% if matrix_hookshot_generic_enabled %}
+generic:
+  # (Optional) Support for generic webhook events. `allowJsTransformationFunctions` will allow users to write short transformation snippets in code, and thus is unsafe in untrusted environments
+  #
+  enabled: {{ matrix_hookshot_generic_enabled }}
+  urlPrefix: {{ matrix_hookshot_generic_urlprefix }}
+  allowJsTransformationFunctions: {{ matrix_hookshot_generic_allow_js_transformation_functions }}
+  userIdPrefix: {{ matrix_hookshot_generic_user_id_prefix|to_json }}
+{% endif %}
+{% if matrix_hookshot_figma_enabled %}
+figma:
+  # (Optional) Configure this to enable Figma support
+  #
+  publicUrl: {{ matrix_hookshot_figma_publicUrl }}
+  instances: {{ matrix_hookshot_figma_instances }}
+{% endif %}
+{% if matrix_hookshot_provisioning_enabled %}
+provisioning:
+  # (Optional) Provisioning API for integration managers
+  #
+  secret: {{ matrix_hookshot_provisioning_secret|to_json }}
+{% endif %}
+passFile:
+  # A passkey used to encrypt tokens stored inside the bridge.
+  # Run openssl genpkey -out passkey.pem -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:4096 to generate
+  #
+  /data/passkey.pem
+bot:
+  # (Optional) Define profile information for the bot user
+  #
+  displayname: {{ matrix_hookshot_bot_displayname }}
+  avatar: {{ matrix_hookshot_bot_avatar }}
+metrics:
+  # (Optional) Prometheus metrics support
+  #
+  enabled: {{ matrix_hookshot_metrics_enabled }}
+logging:
+  # (Optional) Logging settings. You can have a severity debug,info,warn,error
+  #
+  level: info
+{% if matrix_hookshot_permissions %}
+permissions: {{ matrix_hookshot_permissions }}
+{% endif %}
+listeners:
+  # (Optional) HTTP Listener configuration.
+  # Bind resource endpoints to ports and addresses.
+  # 'resources' may be any of webhooks, widgets, metrics, provisioning, appservice
+  #
+{# always enabled since all services need it #}
+  - port: {{ matrix_hookshot_webhook_port }}
+    bindAddress: 0.0.0.0
+    resources:
+      - webhooks
+{% if matrix_hookshot_metrics_enabled %}
+  - port: {{ matrix_hookshot_metrics_port }}
+    bindAddress: 0.0.0.0
+    resources:
+      - metrics
+{% endif %}
+{% if matrix_hookshot_provisioning_enabled %}
+  - port: {{ matrix_hookshot_provisioning_port }}
+    bindAddress: 0.0.0.0
+    resources:
+      - provisioning
+{% endif %}

roles/matrix-bridge-hookshot/templates/registration.yml.j2

@@ -0,0 +1,16 @@
+#jinja2: lstrip_blocks: "True"
+id: matrix-hookshot # This can be anything, but must be unique within your homeserver
+as_token: {{ matrix_hookshot_appservice_token|to_json }} # This again can be a random string
+hs_token: {{ matrix_hookshot_homeserver_token|to_json }} # ..as can this
+namespaces:
+  rooms: []
+  users:
+    - regex: "@_github_.*:{{ matrix_domain }}"
+      exclusive: true
+  aliases:
+    - regex: "#github_.+:{{ matrix_domain }}"
+      exclusive: true
+
+sender_localpart: hookshot
+url: "http://{{ matrix_hookshot_container_url }}:{{ matrix_hookshot_appservice_port }}" # This should match the bridge.port in your config file
+rate_limited: false

roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2

@@ -0,0 +1,40 @@
+#jinja2: lstrip_blocks: "True"
+[Unit]
+Description=A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA.
+{% for service in matrix_hookshot_systemd_required_services_list %}
+Requires={{ service }}
+After={{ service }}
+{% endfor %}
+{% for service in matrix_hookshot_systemd_wanted_services_list %}
+Wants={{ service }}
+{% endfor %}
+DefaultDependencies=no
+
+[Service]
+Type=simple
+Environment="HOME={{ matrix_systemd_unit_home_path }}"
+ExecStartPre=-{{ matrix_host_command_docker }} kill {{ matrix_hookshot_container_url }}
+ExecStartPre=-{{ matrix_host_command_docker }} rm {{ matrix_hookshot_container_url }}
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name {{ matrix_hookshot_container_url }} \
+          --log-driver=none \
+          --user={{ matrix_user_uid }}:{{ matrix_user_gid }} \
+          --cap-drop=ALL \
+          --network={{ matrix_docker_network }} \
+          -v {{ matrix_hookshot_base_path }}:/data:z \
+          {% for port in matrix_hookshot_container_http_host_bind_ports %}
+          -p {{ port }} \
+          {% endfor %}
+          {% for arg in matrix_hookshot_container_extra_arguments %}
+          {{ arg }} \
+          {% endfor %}
+          {{ matrix_hookshot_docker_image }}
+
+ExecStopPost=-{{ matrix_host_command_docker }} kill {{ matrix_hookshot_container_url }}
+ExecStopPost=-{{ matrix_host_command_docker }} rm {{ matrix_hookshot_container_url }}
+Restart=always
+RestartSec=30
+SyslogIdentifier={{ matrix_hookshot_container_url }}
+
+[Install]
+WantedBy=multi-user.target

roles/matrix-prometheus/templates/prometheus.yml.j2

@@ -57,3 +57,9 @@ scrape_configs:
     static_configs:
       - targets: {{ matrix_prometheus_scraper_postgres_targets|to_json }}
   {% endif %}
+
+  {% if matrix_prometheus_scraper_hookshot_enabled %}
+  - job_name: hookshot
+    static_configs:
+      - targets: {{ matrix_prometheus_scraper_hookshot_targets|to_json }}
+  {% endif %}

setup.yml

@@ -36,6 +36,7 @@
     - matrix-bridge-mx-puppet-instagram
     - matrix-bridge-sms
     - matrix-bridge-heisenbridge
+    - matrix-bridge-hookshot
     - matrix-bot-matrix-reminder-bot
     - matrix-bot-honoroit
     - matrix-bot-go-neb