From 621251c1e52993529bc2518d42885307eab83ac1 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Mon, 3 Jan 2022 21:22:42 +0100
Subject: [PATCH 01/38] hookshot role groundwork

---
 docs/configuring-playbook-bridge-hookshot.md  |  16 +++
 group_vars/matrix_servers                     |  36 ++++++
 .../matrix-bridge-hookshot/defaults/main.yml  | 118 ++++++++++++++++++
 roles/matrix-bridge-hookshot/tasks/init.yml   | 101 +++++++++++++++
 roles/matrix-bridge-hookshot/tasks/main.yml   |  15 +++
 .../tasks/setup_install.yml                   |  38 ++++++
 .../tasks/setup_uninstall.yml                 |  28 +++++
 .../templates/config.yml.j2                   | 110 ++++++++++++++++
 .../templates/registration.yml.j2             |  16 +++
 .../systemd/matrix-hookshot.service.j2        |  37 ++++++
 10 files changed, 515 insertions(+)
 create mode 100644 docs/configuring-playbook-bridge-hookshot.md
 create mode 100644 roles/matrix-bridge-hookshot/defaults/main.yml
 create mode 100644 roles/matrix-bridge-hookshot/tasks/init.yml
 create mode 100644 roles/matrix-bridge-hookshot/tasks/main.yml
 create mode 100644 roles/matrix-bridge-hookshot/tasks/setup_install.yml
 create mode 100644 roles/matrix-bridge-hookshot/tasks/setup_uninstall.yml
 create mode 100644 roles/matrix-bridge-hookshot/templates/config.yml.j2
 create mode 100644 roles/matrix-bridge-hookshot/templates/registration.yml.j2
 create mode 100644 roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2

diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md
new file mode 100644
index 000000000..d2bbd7217
--- /dev/null
+++ b/docs/configuring-playbook-bridge-hookshot.md
@@ -0,0 +1,16 @@
+# 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, generic webhooks) fill in the respected variables `matrix_hookshot_service_*` listed in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml) as required.
+2. 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.
+3. Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start bridging things.
+
+Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` variable.
diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 8edcd6baf..7456aad80 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -645,6 +645,42 @@ 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_synapse_macaroon_secret_key) | password_hash('sha512', 'hookshot.as.tok') | to_uuid }}"
+
+matrix_hookshot_homeserver_token: "{{ '%s' | format(matrix_synapse_macaroon_secret_key) | password_hash('sha512', 'hookshot.hs.tok') | to_uuid }}"
+
+matrix_hookshot_systemd_wanted_services_list: |
+  {{
+    (['matrix-synapse.service'] if matrix_synapse_enabled else [])
+    +
+    (['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
+  }}
+
+matrix_hookshot_container_http_host_bind_ports:
+{% if matrix_nginx_proxy_enabled %}
+  []
+{% else %}
+  - "{{ '127.0.0.1:' ~ matrix_hookshot_hookshot_port ~ ':' ~ matrix_hookshot_hookshot_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 }}"
+{% endif %}
+
+######################################################################
+#
+# /matrix-bridge-hookshot
+#
+######################################################################
+
 ######################################################################
 #
 # matrix-bridge-mx-puppet-skype
diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
new file mode 100644
index 000000000..574389080
--- /dev/null
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -0,0 +1,118 @@
+# 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.0.0
+matrix_hookshot_docker_image: "{{ matrix_container_global_registry_prefix }}halfshot/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_public_endpoint: /hookshot
+
+# metrics work only in conjunction with matrix_synapse_metrics_enabled etc
+matrix_hookshot_metrics_enabled: true
+matrix_hookshot_metrics_port: 9001
+
+matrix_hookshot_hookshot_port: 9993
+matrix_hookshot_webhook_port: 9000
+
+# you need to create a GitHub app to enable this
+# https://half-shot.github.io/matrix-hookshot/setup/github.html
+matrix_hookshot_github_enabled: true
+matrix_hookshot_github_appid: 123
+matrix_hookshot_github_private_key: ''
+matrix_hookshot_github_secret: '' # "Webhook secret" on the GitHub App page
+matrix_hookshot_github_oauth_enabled: true
+matrix_hookshot_github_oauth_id: '' # "Client ID" on the GitHub App page
+matrix_hookshot_github_oauth_secret: '' # "Client Secret" on the GitHub App page
+matrix_hookshot_github_oauth_endpoint: "{{ matrix_hookshot_public_endpoint }}/oauth"
+matrix_hookshot_github_oauth_uri: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_github_oauth_endpoint }}"
+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
+matrix_hookshot_gitlab_instances:
+  gitlab.com:
+    url: https://gitlab.com
+
+matrix_hookshot_gitlab_secret: ''
+
+matrix_hookshot_jira_enabled: true
+matrix_hookshot_jira_secret: ''
+matrix_hookshot_jira_oauth_id: ''
+matrix_hookshot_jira_oauth_secret: ''
+matrix_hookshot_jira_oauth_endpoint: "{{ matrix_hookshot_public_endpoint }}/jira/oauth"
+matrix_hookshot_jira_oauth_uri: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_jira_oauth_endpoint }}"
+
+matrix_hookshot_generic_enabled: true
+matrix_hookshot_generic_endpoint: '{{ matrix_hookshot_public_endpoint }}/webhooks'
+matrix_hookshot_generic_urlprefix: '{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_generic_endpoint }}'
+matrix_hookshot_generic_allow_js_transformation_functions: false
+matrix_hookshot_generic_user_id_prefix: 'webhooks_'
+
+# matrix_hookshot_provisioning_port: 9002
+matrix_hookshot_provisioning_secret: ''
+
+# 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: []
+
+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) }}"
diff --git a/roles/matrix-bridge-hookshot/tasks/init.yml b/roles/matrix-bridge-hookshot/tasks/init.yml
new file mode 100644
index 000000000..f71ae8432
--- /dev/null
+++ b/roles/matrix-bridge-hookshot/tasks/init.yml
@@ -0,0 +1,101 @@
+# 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.yaml,dst=/hookshot-registration.yaml,ro"]
+
+    matrix_synapse_app_service_config_files: >
+      {{ matrix_synapse_app_service_config_files|default([]) }}
+      +
+      {{ ["/hookshot-registration.yaml"] }}
+  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_appservice_webhooks_matrix_nginx_proxy_configuration: |
+        location ~ ^{{ matrix_hookshot_public_endpoint }}/metrics$ {
+          {% 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:{{ 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_nginx_proxy_proxy_synapse_metrics_basic_auth_enabled %}
+            auth_basic "protected";
+            auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
+          {% endif %}
+        }
+        location ~ ^{{ matrix_hookshot_generic_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:{{ 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;
+        }
+        {% if matrix_nginx_proxy_enabled|default(False) %}
+        {# Use the embedded DNS resolver in Docker containers to discover the service #}
+        location ~ ^{{ matrix_hookshot_public_endpoint }}/(.*)$ {
+          resolver 127.0.0.11 valid=5s;
+          set $backend "matrix-hookshot:{{ matrix_hookshot_hookshot_port }}";
+          proxy_pass http://$backend/$1;
+        }
+        {% else %}
+        {# Generic configuration for use outside of our container setup #}
+        location {{ matrix_hookshot_public_endpoint }}/ {
+          proxy_pass http://127.0.0.1:{{ matrix_hookshot_hookshot_port }}/;
+        }
+        {% endif %}
+
+  - name: Register webhooks Appservice 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]
+        }}
+  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_appservice_webhooks_enabled|bool and matrix_nginx_proxy_enabled is not defined"
diff --git a/roles/matrix-bridge-hookshot/tasks/main.yml b/roles/matrix-bridge-hookshot/tasks/main.yml
new file mode 100644
index 000000000..52d90aa1e
--- /dev/null
+++ b/roles/matrix-bridge-hookshot/tasks/main.yml
@@ -0,0 +1,15 @@
+- import_tasks: "{{ role_path }}/tasks/init.yml"
+  tags:
+    - always
+
+- 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
diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
new file mode 100644
index 000000000..55f37c8df
--- /dev/null
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -0,0 +1,38 @@
+---
+
+- 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: Ensure hookshot registration.yaml installed if provided
+  copy:
+    content: "{{ matrix_hookshot_registration|to_nice_yaml }}"
+    dest: "{{ matrix_hookshot_base_path }}/registration.yaml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
+- 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
diff --git a/roles/matrix-bridge-hookshot/tasks/setup_uninstall.yml b/roles/matrix-bridge-hookshot/tasks/setup_uninstall.yml
new file mode 100644
index 000000000..52e126e9d
--- /dev/null
+++ b/roles/matrix-bridge-hookshot/tasks/setup_uninstall.yml
@@ -0,0 +1,28 @@
+---
+
+- 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"
+
+# remove base_path?
+# remove docker image?
diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
new file mode 100644
index 000000000..f23c67483
--- /dev/null
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -0,0 +1,110 @@
+#jinja2: lstrip_blocks: "True"
+bridge:
+  # Basic homeserver configuration
+  #
+  domain: {{ matrix_domain }}
+  url: {{ matrix_hookshot_homeserver_address }}
+  mediaUrl: { matrix_hookshot_homeserver_address }}
+  port: {{ matrix_hookshot_hookshot_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: {{ matrix_hookshot_github_private_key }}
+  webhook:
+    # Webhook settings for the GitHub app.
+    #
+    secret: {{ matrix_hookshot_github_secret }}
+{% 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 }}
+    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 }}
+{% endif %}
+{% if matrix_hookshot_jira_enabled %}
+jira:
+  # (Optional) Configure this to enable Jira support
+  #
+  webhook:
+    secret: {{ matrix_hookshot_jira_secret }}
+  oauth:
+    client_id: {{ matrix_hookshot_jira_oauth_id }}
+    client_secret: {{ matrix_hookshot_jira_oauth_secret }}
+    redirect_uri: {{ matrix_hookshot_jira_oauth_uri }}
+{% 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 }}
+{% endif %}
+provisioning:
+  # (Optional) Provisioning API for integration managers
+  #
+  secret: {{ matrix_hookshot_provisioning_secret }}
+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
+  #
+  passkey.pem
+bot:
+  # (Optional) Define profile information for the bot user
+  #
+  displayname: GitHub Bot
+  avatar: mxc://half-shot.uk/2876e89ccade4cb615e210c458e2a7a6883fe17d
+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
+listeners:
+  # (Optional) HTTP Listener configuration.
+  # Bind resource endpoints to ports and addresses.
+  # 'resources' may be any of webhooks, widgets, metrics, provisioning, appservice
+  #
+  - port: {{ matrix_hookshot_webhook_port }}
+    bindAddress: 0.0.0.0
+    resources:
+      - webhooks
+      - widgets
+  - port: {{ matrix_hookshot_metrics_port }}
+    bindAddress: 0.0.0.0
+    resources:
+      - metrics
+  - port: {{ matrix_hookshot_hookshot_port }}
+    bindAddress: 0.0.0.0
+    resources:
+      - provisioning
+      - appservice
diff --git a/roles/matrix-bridge-hookshot/templates/registration.yml.j2 b/roles/matrix-bridge-hookshot/templates/registration.yml.j2
new file mode 100644
index 000000000..24cd1f4cd
--- /dev/null
+++ b/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 }} # This again can be a random string
+hs_token: {{ matrix_hookshot_homeserver_token }} # ..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_hookshot_port }}" # This should match the bridge.port in your config file
+rate_limited: false
diff --git a/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2 b/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
new file mode 100644
index 000000000..c06456af5
--- /dev/null
+++ b/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
@@ -0,0 +1,37 @@
+#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
+ExecStartPre=-{{ matrix_host_command_docker }} rm matrix-hookshot
+
+ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-hookshot \
+          --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 arg in matrix_hookshot_container_extra_arguments %}
+          {{ arg }} \
+          {% endfor %}
+          {{ matrix_hookshot_docker_image }}
+
+ExecStop=-{{ matrix_host_command_docker }} kill matrix-hookshot
+ExecStop=-{{ matrix_host_command_docker }} rm matrix-hookshot
+Restart=always
+RestartSec=30
+SyslogIdentifier=matrix-hookshot
+
+[Install]
+WantedBy=multi-user.target

From b8ee1980ea559615d66b8130122fed83606758e4 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Thu, 6 Jan 2022 18:55:36 +0100
Subject: [PATCH 02/38] refine hookshot role

---
 docs/configuring-playbook-bridge-hookshot.md  |  5 +-
 .../matrix-bridge-hookshot/defaults/main.yml  | 58 +++++++++++++++----
 roles/matrix-bridge-hookshot/tasks/init.yml   | 45 +++++++++-----
 .../tasks/setup_install.yml                   | 21 +++++++
 .../templates/config.yml.j2                   | 22 +++++--
 .../systemd/matrix-hookshot.service.j2        |  3 +
 6 files changed, 119 insertions(+), 35 deletions(-)

diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md
index d2bbd7217..a1fefa427 100644
--- a/docs/configuring-playbook-bridge-hookshot.md
+++ b/docs/configuring-playbook-bridge-hookshot.md
@@ -10,7 +10,8 @@ See the project's [documentation](https://half-shot.github.io/matrix-hookshot/ho
 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, generic webhooks) fill in the respected variables `matrix_hookshot_service_*` listed in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml) as required.
-2. 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.
-3. Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start bridging things.
+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'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`.
+4. Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge.
 
 Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` variable.
diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index 574389080..f1f98c04e 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -13,28 +13,35 @@ matrix_hookshot_homeserver_address: "{{ matrix_homeserver_container_url }}"
 
 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. 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"
 
-matrix_hookshot_hookshot_port: 9993
+# 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
 # https://half-shot.github.io/matrix-hookshot/setup/github.html
-matrix_hookshot_github_enabled: true
-matrix_hookshot_github_appid: 123
+matrix_hookshot_github_enabled: false
+matrix_hookshot_github_appid: ''
 matrix_hookshot_github_private_key: ''
 matrix_hookshot_github_secret: '' # "Webhook secret" on the GitHub App page
-matrix_hookshot_github_oauth_enabled: true
+matrix_hookshot_github_oauth_enabled: false
 matrix_hookshot_github_oauth_id: '' # "Client ID" on the GitHub App page
 matrix_hookshot_github_oauth_secret: '' # "Client Secret" on the GitHub App page
-matrix_hookshot_github_oauth_endpoint: "{{ matrix_hookshot_public_endpoint }}/oauth"
+matrix_hookshot_github_oauth_endpoint: "{{ matrix_hookshot_webhook_endpoint }}/oauth"
 matrix_hookshot_github_oauth_uri: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_github_oauth_endpoint }}"
-matrix_hookshot_github_ignore_hooks: '{}'
+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_pr_diff: "{enabled: false, maxLines: 5}"
 matrix_hookshot_github_including_labels: ''
 matrix_hookshot_github_excluding_labels: ''
 
@@ -45,21 +52,37 @@ matrix_hookshot_gitlab_instances:
 
 matrix_hookshot_gitlab_secret: ''
 
-matrix_hookshot_jira_enabled: true
+matrix_hookshot_jira_enabled: false
 matrix_hookshot_jira_secret: ''
 matrix_hookshot_jira_oauth_id: ''
 matrix_hookshot_jira_oauth_secret: ''
-matrix_hookshot_jira_oauth_endpoint: "{{ matrix_hookshot_public_endpoint }}/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 }}"
 
 matrix_hookshot_generic_enabled: true
-matrix_hookshot_generic_endpoint: '{{ matrix_hookshot_public_endpoint }}/webhooks'
-matrix_hookshot_generic_urlprefix: '{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_generic_endpoint }}'
+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
 matrix_hookshot_generic_user_id_prefix: 'webhooks_'
 
-# matrix_hookshot_provisioning_port: 9002
+matrix_hookshot_figma_enabled: false
+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
+
+matrix_hookshot_provisioning_enabled: true
+# 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: ''
+matrix_hookshot_provisioning_endpoint: "{{ matrix_hookshot_public_endpoint }}/v1"
+
+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: []
@@ -70,6 +93,17 @@ 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: []
+
 matrix_hookshot_appservice_token: ''
 matrix_hookshot_homeserver_token: ''
 
diff --git a/roles/matrix-bridge-hookshot/tasks/init.yml b/roles/matrix-bridge-hookshot/tasks/init.yml
index f71ae8432..11ac01380 100644
--- a/roles/matrix-bridge-hookshot/tasks/init.yml
+++ b/roles/matrix-bridge-hookshot/tasks/init.yml
@@ -36,7 +36,8 @@
   - name: Generate Matrix hookshot proxying configuration for matrix-nginx-proxy
     set_fact:
       matrix_appservice_webhooks_matrix_nginx_proxy_configuration: |
-        location ~ ^{{ matrix_hookshot_public_endpoint }}/metrics$ {
+        {% if matrix_hookshot_metrics_enabled %}
+        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;
@@ -52,7 +53,34 @@
             auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
           {% endif %}
         }
-        location ~ ^{{ matrix_hookshot_generic_endpoint }}/(.*)$ {
+        {% endif %}
+        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:{{ 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:{{ 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;
@@ -64,19 +92,6 @@
           {% endif %}
           proxy_set_header Host $host;
         }
-        {% if matrix_nginx_proxy_enabled|default(False) %}
-        {# Use the embedded DNS resolver in Docker containers to discover the service #}
-        location ~ ^{{ matrix_hookshot_public_endpoint }}/(.*)$ {
-          resolver 127.0.0.11 valid=5s;
-          set $backend "matrix-hookshot:{{ matrix_hookshot_hookshot_port }}";
-          proxy_pass http://$backend/$1;
-        }
-        {% else %}
-        {# Generic configuration for use outside of our container setup #}
-        location {{ matrix_hookshot_public_endpoint }}/ {
-          proxy_pass http://127.0.0.1:{{ matrix_hookshot_hookshot_port }}/;
-        }
-        {% endif %}
 
   - name: Register webhooks Appservice proxying configuration with matrix-nginx-proxy
     set_fact:
diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
index 55f37c8df..2254d91cd 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_install.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -17,6 +17,27 @@
   with_items:
     - "{{ matrix_hookshot_base_path }}"
 
+# - name: Ensure openssl is installed (#1510)
+
+- name: Check if hookshot passkey exists
+  stat:
+    path: "{{ matrix_hookshot_data_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.yaml installed if provided
+  copy:
+    content: "{{ matrix_hookshot_config|to_nice_yaml }}"
+    dest: "{{ matrix_hookshot_base_path }}/config.yaml"
+    mode: 0644
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
 - name: Ensure hookshot registration.yaml installed if provided
   copy:
     content: "{{ matrix_hookshot_registration|to_nice_yaml }}"
diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index f23c67483..2dc87f3c6 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -5,7 +5,7 @@ bridge:
   domain: {{ matrix_domain }}
   url: {{ matrix_hookshot_homeserver_address }}
   mediaUrl: { matrix_hookshot_homeserver_address }}
-  port: {{ matrix_hookshot_hookshot_port }}
+  port: {{ matrix_hookshot_appservice_port }}
   bindAddress: 0.0.0.0
 {% if matrix_hookshot_github_enabled %}
 github:
@@ -67,6 +67,13 @@ generic:
   allowJsTransformationFunctions: {{ matrix_hookshot_generic_allow_js_transformation_functions }}
   userIdPrefix: {{ matrix_hookshot_generic_user_id_prefix }}
 {% endif %}
+{% if matrix_hookshot_figma_enabled %}
+figma:
+  # (Optional) Configure this to enable Figma support
+  #
+  publicUrl: https://example.com/hookshot/
+  instances: {{ matrix_hookshot_figma_instances }}
+{% endif %}
 provisioning:
   # (Optional) Provisioning API for integration managers
   #
@@ -79,8 +86,8 @@ passFile:
 bot:
   # (Optional) Define profile information for the bot user
   #
-  displayname: GitHub Bot
-  avatar: mxc://half-shot.uk/2876e89ccade4cb615e210c458e2a7a6883fe17d
+  displayname: {{ matrix_hookshot_bot_displayname }}
+  avatar: {{ matrix_hookshot_bot_avatar }}
 metrics:
   # (Optional) Prometheus metrics support
   #
@@ -94,17 +101,20 @@ listeners:
   # 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
-      - widgets
+{% if matrix_hookshot_metrics_enabled %}
   - port: {{ matrix_hookshot_metrics_port }}
     bindAddress: 0.0.0.0
     resources:
       - metrics
-  - port: {{ matrix_hookshot_hookshot_port }}
+{% endif %}
+{% if matrix_hookshot_provisioning_enabled %}
+  - port: {{ matrix_hookshot_provisioning_port }}
     bindAddress: 0.0.0.0
     resources:
       - provisioning
-      - appservice
+{% endif %}
diff --git a/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2 b/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
index c06456af5..a291de987 100644
--- a/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
+++ b/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
@@ -22,6 +22,9 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-hookshot \
           --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 %}

From 495bfedc0d35f983000185c469e941501d126d10 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sat, 8 Jan 2022 16:51:52 +0100
Subject: [PATCH 03/38] refine hookshot role using `--test`

---
 roles/matrix-bridge-hookshot/defaults/main.yml     |  1 +
 roles/matrix-bridge-hookshot/tasks/init.yml        | 14 +++++++-------
 .../matrix-bridge-hookshot/tasks/setup_install.yml |  4 ++--
 .../matrix-bridge-hookshot/templates/config.yml.j2 |  2 +-
 .../templates/registration.yml.j2                  |  2 +-
 .../templates/systemd/matrix-hookshot.service.j2   | 12 ++++++------
 setup.yml                                          |  1 +
 7 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index f1f98c04e..d96f08228 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -10,6 +10,7 @@ matrix_hookshot_docker_image_force_pull: "{{ matrix_hookshot_docker_image.endswi
 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
 
diff --git a/roles/matrix-bridge-hookshot/tasks/init.yml b/roles/matrix-bridge-hookshot/tasks/init.yml
index 11ac01380..f6c7c107f 100644
--- a/roles/matrix-bridge-hookshot/tasks/init.yml
+++ b/roles/matrix-bridge-hookshot/tasks/init.yml
@@ -35,13 +35,13 @@
 
   - name: Generate Matrix hookshot proxying configuration for matrix-nginx-proxy
     set_fact:
-      matrix_appservice_webhooks_matrix_nginx_proxy_configuration: |
+      matrix_hookshot_matrix_nginx_proxy_configuration: |
         {% if matrix_hookshot_metrics_enabled %}
         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:{{ matrix_hookshot_metrics_port }}";
+            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 #}
@@ -58,7 +58,7 @@
           {% 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:{{ matrix_hookshot_appservice_port }}";
+            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 #}
@@ -71,7 +71,7 @@
           {% 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:{{ matrix_hookshot_provisioning_port }}";
+            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 #}
@@ -84,7 +84,7 @@
           {% 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:{{ matrix_hookshot_webhook_port }}";
+            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 #}
@@ -93,7 +93,7 @@
           proxy_set_header Host $host;
         }
 
-  - name: Register webhooks Appservice proxying configuration with matrix-nginx-proxy
+  - name: Register hookshot proxying configuration with matrix-nginx-proxy
     set_fact:
       matrix_nginx_proxy_proxy_matrix_additional_server_configuration_blocks: |
         {{
@@ -113,4 +113,4 @@
       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_appservice_webhooks_enabled|bool and matrix_nginx_proxy_enabled is not defined"
+  when: "matrix_hookshot_enabled|bool and matrix_nginx_proxy_enabled is not defined"
diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
index 2254d91cd..13bc324ba 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_install.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -21,7 +21,7 @@
 
 - name: Check if hookshot passkey exists
   stat:
-    path: "{{ matrix_hookshot_data_path }}/passkey.pem"
+    path: "{{ matrix_hookshot_base_path }}/passkey.pem"
   register: hookshot_passkey_file
 
 - name: Generate hookshot passkey if it doesn't exist
@@ -32,7 +32,7 @@
 
 - name: Ensure hookshot config.yaml installed if provided
   copy:
-    content: "{{ matrix_hookshot_config|to_nice_yaml }}"
+    content: "{{ matrix_hookshot_configuration|to_nice_yaml }}"
     dest: "{{ matrix_hookshot_base_path }}/config.yaml"
     mode: 0644
     owner: "{{ matrix_user_username }}"
diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index 2dc87f3c6..83d84863d 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -4,7 +4,7 @@ bridge:
   #
   domain: {{ matrix_domain }}
   url: {{ matrix_hookshot_homeserver_address }}
-  mediaUrl: { matrix_hookshot_homeserver_address }}
+  mediaUrl: {{ matrix_hookshot_homeserver_address }}
   port: {{ matrix_hookshot_appservice_port }}
   bindAddress: 0.0.0.0
 {% if matrix_hookshot_github_enabled %}
diff --git a/roles/matrix-bridge-hookshot/templates/registration.yml.j2 b/roles/matrix-bridge-hookshot/templates/registration.yml.j2
index 24cd1f4cd..e86426c80 100644
--- a/roles/matrix-bridge-hookshot/templates/registration.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/registration.yml.j2
@@ -12,5 +12,5 @@ namespaces:
       exclusive: true
 
 sender_localpart: hookshot
-url: "http://{{ matrix_hookshot_container_url }}:{{ matrix_hookshot_hookshot_port }}" # This should match the bridge.port in your config file
+url: "http://{{ matrix_hookshot_container_url }}:{{ matrix_hookshot_appservice_port }}" # This should match the bridge.port in your config file
 rate_limited: false
diff --git a/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2 b/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
index a291de987..16ff05920 100644
--- a/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
+++ b/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
@@ -13,10 +13,10 @@ DefaultDependencies=no
 [Service]
 Type=simple
 Environment="HOME={{ matrix_systemd_unit_home_path }}"
-ExecStartPre=-{{ matrix_host_command_docker }} kill matrix-hookshot
-ExecStartPre=-{{ matrix_host_command_docker }} rm matrix-hookshot
+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 \
+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 \
@@ -30,11 +30,11 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name matrix-hookshot \
           {% endfor %}
           {{ matrix_hookshot_docker_image }}
 
-ExecStop=-{{ matrix_host_command_docker }} kill matrix-hookshot
-ExecStop=-{{ matrix_host_command_docker }} rm matrix-hookshot
+ExecStop=-{{ matrix_host_command_docker }} kill {{ matrix_hookshot_container_url }}
+ExecStop=-{{ matrix_host_command_docker }} rm {{ matrix_hookshot_container_url }}
 Restart=always
 RestartSec=30
-SyslogIdentifier=matrix-hookshot
+SyslogIdentifier={{ matrix_hookshot_container_url }}
 
 [Install]
 WantedBy=multi-user.target
diff --git a/setup.yml b/setup.yml
index edd212057..81ab79b04 100755
--- a/setup.yml
+++ b/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-go-neb
     - matrix-bot-mjolnir

From 912c2388477465a2e6d892a63716cad0a9a69ae7 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sat, 8 Jan 2022 16:52:09 +0100
Subject: [PATCH 04/38] Upgrade Hookshot (1.0.0 -> 1.1.0)

---
 roles/matrix-bridge-hookshot/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index d96f08228..27d6e8a9c 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -3,7 +3,7 @@
 
 matrix_hookshot_enabled: true
 
-matrix_hookshot_version: 1.0.0
+matrix_hookshot_version: 1.1.0
 matrix_hookshot_docker_image: "{{ matrix_container_global_registry_prefix }}halfshot/hookshot:{{ matrix_hookshot_version }}"
 matrix_hookshot_docker_image_force_pull: "{{ matrix_hookshot_docker_image.endswith(':latest') }}"
 

From ebf33f46b7cc80ea9c592673d91cc4de16da308e Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sat, 8 Jan 2022 16:55:27 +0100
Subject: [PATCH 05/38] update hookshot passkey.pem path according to docs

https://github.com/Half-Shot/matrix-hookshot/issues/133#issuecomment-1007541580
---
 roles/matrix-bridge-hookshot/templates/config.yml.j2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index 83d84863d..3ae7d2dd2 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -82,7 +82,7 @@ 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
   #
-  passkey.pem
+  /data/passkey.pem
 bot:
   # (Optional) Define profile information for the bot user
   #

From e0f2aa9de809820257c2ae6960159c767ac3f607 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sat, 8 Jan 2022 17:16:53 +0100
Subject: [PATCH 06/38] refactor matrix_hookshot_container_http_host_bind_ports

---
 group_vars/matrix_servers | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 7456aad80..b5f4fa4db 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -665,15 +665,13 @@ matrix_hookshot_systemd_wanted_services_list: |
     (['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
   }}
 
-matrix_hookshot_container_http_host_bind_ports:
-{% if matrix_nginx_proxy_enabled %}
-  []
-{% else %}
-  - "{{ '127.0.0.1:' ~ matrix_hookshot_hookshot_port ~ ':' ~ matrix_hookshot_hookshot_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 }}"
-{% endif %}
+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: matrix_hookshot_container_http_host_bind_ports_defaultmapping if matrix_nginx_proxy_enabled else []
 
 ######################################################################
 #

From 1987cc48390c99d073d6ace9f03a7ce3b006a05f Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Tue, 11 Jan 2022 00:19:29 +0100
Subject: [PATCH 07/38] refine hookshot role

---
 docs/configuring-playbook-bridge-hookshot.md  |  8 ++-
 group_vars/matrix_servers                     |  2 +
 .../matrix-bridge-hookshot/defaults/main.yml  | 28 ++++++++++-
 roles/matrix-bridge-hookshot/tasks/init.yml   | 49 ++++++++++++-------
 .../tasks/setup_install.yml                   |  5 +-
 .../templates/config.yml.j2                   |  4 ++
 6 files changed, 72 insertions(+), 24 deletions(-)

diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md
index a1fefa427..4a9d8fb0b 100644
--- a/docs/configuring-playbook-bridge-hookshot.md
+++ b/docs/configuring-playbook-bridge-hookshot.md
@@ -9,9 +9,13 @@ See the project's [documentation](https://half-shot.github.io/matrix-hookshot/ho
 
 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, generic webhooks) fill in the respected variables `matrix_hookshot_service_*` listed in [main.yml](roles/matrix-bridge-hookshot/defaults/main.yml) as required.
+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'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`.
 4. Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge.
 
-Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` variable.
+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`.
+
+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). See also [the Prometheus and Grafana docs](../configuring-playbook-prometheus-grafana.md).
+
+Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in `/roles/matrix-bridge-hookshot/defaults/main.yml` for how to use them.
diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index b5f4fa4db..5320e8ec0 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -673,6 +673,8 @@ matrix_hookshot_container_http_host_bind_ports_defaultmapping:
 
 matrix_hookshot_container_http_host_bind_ports: matrix_hookshot_container_http_host_bind_ports_defaultmapping if matrix_nginx_proxy_enabled else []
 
+matrix_hookshot_provisioning_enabled: "{{ true if matrix_hookshot_provisioning_secret and matrix_dimension_enabled else false}}"
+
 ######################################################################
 #
 # /matrix-bridge-hookshot
diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index 27d6e8a9c..20326a0c5 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -28,17 +28,21 @@ matrix_hookshot_metrics_endpoint: "{{ matrix_hookshot_public_endpoint }}/metrics
 matrix_hookshot_webhook_port: 9000
 matrix_hookshot_webhook_endpoint: "{{ matrix_hookshot_public_endpoint }}/webhooks"
 
-# you need to create a GitHub app to enable this
+
+# 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: ''
 matrix_hookshot_github_private_key: ''
 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: "{{ 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
@@ -46,27 +50,44 @@ 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
 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:
@@ -76,12 +97,15 @@ matrix_hookshot_figma_publicUrl: "{{ matrix_server_fqn_matrix }}{{ matrix_hooksh
 #       accessToken: your-personal-access-token
 #       passcode: your-webhook-passcode
 
-matrix_hookshot_provisioning_enabled: true
+
 # 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"
 
+
 matrix_hookshot_bot_displayname: Hookshot Bot
 matrix_hookshot_bot_avatar: 'mxc://half-shot.uk/2876e89ccade4cb615e210c458e2a7a6883fe17d'
 
diff --git a/roles/matrix-bridge-hookshot/tasks/init.yml b/roles/matrix-bridge-hookshot/tasks/init.yml
index f6c7c107f..e7b52cfd6 100644
--- a/roles/matrix-bridge-hookshot/tasks/init.yml
+++ b/roles/matrix-bridge-hookshot/tasks/init.yml
@@ -36,24 +36,6 @@
   - name: Generate Matrix hookshot proxying configuration for matrix-nginx-proxy
     set_fact:
       matrix_hookshot_matrix_nginx_proxy_configuration: |
-        {% if matrix_hookshot_metrics_enabled %}
-        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_nginx_proxy_proxy_synapse_metrics_basic_auth_enabled %}
-            auth_basic "protected";
-            auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
-          {% endif %}
-        }
-        {% endif %}
         location ~ ^{{ matrix_hookshot_appservice_endpoint }}/(.*)$ {
           {% if matrix_nginx_proxy_enabled|default(False) %}
             {# Use the embedded DNS resolver in Docker containers to discover the service #}
@@ -101,6 +83,37 @@
           +
           [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 %}
+        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_nginx_proxy_proxy_synapse_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
diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
index 13bc324ba..4892fa584 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_install.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -1,5 +1,8 @@
 ---
 
+#  (#1510)
+# - 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 }}"
@@ -17,8 +20,6 @@
   with_items:
     - "{{ matrix_hookshot_base_path }}"
 
-# - name: Ensure openssl is installed (#1510)
-
 - name: Check if hookshot passkey exists
   stat:
     path: "{{ matrix_hookshot_base_path }}/passkey.pem"
diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index 3ae7d2dd2..c188611cd 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -53,11 +53,13 @@ jira:
   #
   webhook:
     secret: {{ matrix_hookshot_jira_secret }}
+{% if matrix_hookshot_jira_oauth_enabled %}
   oauth:
     client_id: {{ matrix_hookshot_jira_oauth_id }}
     client_secret: {{ matrix_hookshot_jira_oauth_secret }}
     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
@@ -74,10 +76,12 @@ figma:
   publicUrl: https://example.com/hookshot/
   instances: {{ matrix_hookshot_figma_instances }}
 {% endif %}
+{% if matrix_hookshot_provisioning_enabled %}
 provisioning:
   # (Optional) Provisioning API for integration managers
   #
   secret: {{ matrix_hookshot_provisioning_secret }}
+{% 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

From 87871040df532b77aa770c4f92670867bc69c744 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Tue, 11 Jan 2022 00:56:51 +0100
Subject: [PATCH 08/38] add hookshot metrics to internal prometheus

---
 docs/configuring-playbook-bridge-hookshot.md        | 2 +-
 group_vars/matrix_servers                           | 2 ++
 roles/matrix-bridge-hookshot/defaults/main.yml      | 4 +++-
 roles/matrix-prometheus/templates/prometheus.yml.j2 | 6 ++++++
 4 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md
index 4a9d8fb0b..2ad5154bd 100644
--- a/docs/configuring-playbook-bridge-hookshot.md
+++ b/docs/configuring-playbook-bridge-hookshot.md
@@ -16,6 +16,6 @@ Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot
 
 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`.
 
-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). See also [the Prometheus and Grafana docs](../configuring-playbook-prometheus-grafana.md).
+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).
 
 Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in `/roles/matrix-bridge-hookshot/defaults/main.yml` for how to use them.
diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 5320e8ec0..325d7ba02 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -1967,6 +1967,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 [] }}"
 
 ######################################################################
 #
diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index 20326a0c5..33f439d62 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -20,7 +20,9 @@ matrix_hookshot_appservice_endpoint: "{{ matrix_hookshot_public_endpoint }}/_mat
 
 # metrics work only in conjunction with matrix_synapse_metrics_enabled etc
 matrix_hookshot_metrics_enabled: true
-# there is no need to edit ports. use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
+# 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"
 
diff --git a/roles/matrix-prometheus/templates/prometheus.yml.j2 b/roles/matrix-prometheus/templates/prometheus.yml.j2
index 869b2da8d..f3262f485 100644
--- a/roles/matrix-prometheus/templates/prometheus.yml.j2
+++ b/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 %}

From 65991de61c6a7e102ffb077dcfca87a6ec6d61d3 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Tue, 11 Jan 2022 01:30:57 +0100
Subject: [PATCH 09/38] update hookshot private key file mechanism

---
 docs/configuring-playbook-bridge-hookshot.md         | 6 ++++--
 roles/matrix-bridge-hookshot/defaults/main.yml       | 3 ++-
 roles/matrix-bridge-hookshot/tasks/setup_install.yml | 8 ++++++++
 roles/matrix-bridge-hookshot/templates/config.yml.j2 | 2 +-
 4 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md
index 2ad5154bd..0dfdfd501 100644
--- a/docs/configuring-playbook-bridge-hookshot.md
+++ b/docs/configuring-playbook-bridge-hookshot.md
@@ -11,8 +11,10 @@ Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot
 
 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'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`.
-4. Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge.
+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. Before running the playbook, you need to copy that file to `/roles/matrix-bridge-hookshot/files/github-key.pem` so the playbook can install it for you.
+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 the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge.
+
 
 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`.
 
diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index 33f439d62..36dd361e9 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -35,7 +35,8 @@ matrix_hookshot_webhook_endpoint: "{{ matrix_hookshot_public_endpoint }}/webhook
 # https://half-shot.github.io/matrix-hookshot/setup/github.html
 matrix_hookshot_github_enabled: false
 matrix_hookshot_github_appid: ''
-matrix_hookshot_github_private_key: ''
+# manually copy the generated and downloaded GitHub private key to /roles/matrix-bridge-hookshot/files/github-key.pem
+matrix_hookshot_github_private_key: 'github-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)
diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
index 4892fa584..271dacba2 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_install.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -47,6 +47,14 @@
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
 
+- name: Ensure hookshot github private key file installed if github is enabled
+  copy:
+    src: github-key.pem
+    dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key }}"
+    mode: 0600
+    owner: "{{ matrix_user_username }}"
+    group: "{{ matrix_user_groupname }}"
+
 - name: Ensure matrix-hookshot.service installed
   template:
     src: "{{ role_path }}/templates/systemd/matrix-hookshot.service.j2"
diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index c188611cd..702245c37 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -15,7 +15,7 @@ github:
     # Authentication for the GitHub App.
     #
     id: {{ matrix_hookshot_github_appid }}
-    privateKeyFile: {{ matrix_hookshot_github_private_key }}
+    privateKeyFile: /data/{{ matrix_hookshot_github_private_key }}
   webhook:
     # Webhook settings for the GitHub app.
     #

From 206a093d5600296a5de2b7401d0f6889a5537ae0 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Tue, 11 Jan 2022 22:35:57 +0100
Subject: [PATCH 10/38] fix hookshot docker image name

---
 roles/matrix-bridge-hookshot/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index 36dd361e9..5a5b6c920 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -4,7 +4,7 @@
 matrix_hookshot_enabled: true
 
 matrix_hookshot_version: 1.1.0
-matrix_hookshot_docker_image: "{{ matrix_container_global_registry_prefix }}halfshot/hookshot:{{ matrix_hookshot_version }}"
+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"

From 8b19f56ef874d7d6408b3bfb289426857f8f0d59 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Tue, 11 Jan 2022 22:36:10 +0100
Subject: [PATCH 11/38] add hookshot config validation

---
 .../tasks/setup_install.yml                      | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
index 271dacba2..3aa77642a 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_install.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -39,6 +39,22 @@
     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.yaml installed if provided
   copy:
     content: "{{ matrix_hookshot_registration|to_nice_yaml }}"

From 3a766d4ba5039997f97ec20b1950424b052d6c7f Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Tue, 11 Jan 2022 22:39:57 +0100
Subject: [PATCH 12/38] proxy hookshot metrics when proxying synapse metrics

see also #1527
---
 group_vars/matrix_servers                   | 3 +++
 roles/matrix-bridge-hookshot/tasks/init.yml | 4 ++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 325d7ba02..a923437ac 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -675,6 +675,9 @@ matrix_hookshot_container_http_host_bind_ports: matrix_hookshot_container_http_h
 
 matrix_hookshot_provisioning_enabled: "{{ true if matrix_hookshot_provisioning_secret and matrix_dimension_enabled else false}}"
 
+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
diff --git a/roles/matrix-bridge-hookshot/tasks/init.yml b/roles/matrix-bridge-hookshot/tasks/init.yml
index e7b52cfd6..7dc781c6d 100644
--- a/roles/matrix-bridge-hookshot/tasks/init.yml
+++ b/roles/matrix-bridge-hookshot/tasks/init.yml
@@ -87,7 +87,7 @@
   - name: Generate Matrix hookshot proxying configuration for matrix-nginx-proxy
     set_fact:
       matrix_hookshot_matrix_nginx_proxy_metrics_configuration: |
-        {% if matrix_hookshot_metrics_enabled %}
+        {% 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 #}
@@ -99,7 +99,7 @@
             proxy_pass http://127.0.0.1:{{ matrix_hookshot_metrics_port }}/metrics;
           {% endif %}
           proxy_set_header Host $host;
-          {% if matrix_nginx_proxy_proxy_synapse_metrics_basic_auth_enabled %}
+          {% if matrix_hookshot_proxy_metrics_basic_auth_enabled %}
             auth_basic "protected";
             auth_basic_user_file /nginx-data/matrix-synapse-metrics-htpasswd;
           {% endif %}

From 964479d3d341f36fbeccb3fbdcc692138f2922de Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Tue, 11 Jan 2022 23:03:16 +0100
Subject: [PATCH 13/38] .gitkeep matrix-bridge-hookshot/files

needed for users to put private-key.pem in
---
 roles/matrix-bridge-hookshot/files/.gitkeep | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 roles/matrix-bridge-hookshot/files/.gitkeep

diff --git a/roles/matrix-bridge-hookshot/files/.gitkeep b/roles/matrix-bridge-hookshot/files/.gitkeep
new file mode 100644
index 000000000..e69de29bb

From 23d6b2d3daf9fb9b2a2602474ade49d2e23f793b Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Tue, 11 Jan 2022 23:18:47 +0100
Subject: [PATCH 14/38] update hookshot github private key path and install
 condition

---
 roles/matrix-bridge-hookshot/defaults/main.yml       | 4 ++--
 roles/matrix-bridge-hookshot/tasks/setup_install.yml | 1 +
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index 5a5b6c920..e548e51fa 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -35,8 +35,8 @@ matrix_hookshot_webhook_endpoint: "{{ matrix_hookshot_public_endpoint }}/webhook
 # https://half-shot.github.io/matrix-hookshot/setup/github.html
 matrix_hookshot_github_enabled: false
 matrix_hookshot_github_appid: ''
-# manually copy the generated and downloaded GitHub private key to /roles/matrix-bridge-hookshot/files/github-key.pem
-matrix_hookshot_github_private_key: 'github-key.pem'
+# manually copy the generated and downloaded GitHub private key to roles/matrix-bridge-hookshot/files/private-key.pem
+matrix_hookshot_github_private_key: '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)
diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
index 3aa77642a..0caba20fc 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_install.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -70,6 +70,7 @@
     mode: 0600
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
+  when: "matrix_hookshot_github_enabled|bool"
 
 - name: Ensure matrix-hookshot.service installed
   template:

From f12cad7a7bd0aee12a43aeaafba82f1cc2cc3859 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Tue, 11 Jan 2022 23:34:03 +0100
Subject: [PATCH 15/38] rename hookshot *.yaml to *.yml

---
 roles/matrix-bridge-hookshot/tasks/init.yml          | 4 ++--
 roles/matrix-bridge-hookshot/tasks/setup_install.yml | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/roles/matrix-bridge-hookshot/tasks/init.yml b/roles/matrix-bridge-hookshot/tasks/init.yml
index 7dc781c6d..67b793d44 100644
--- a/roles/matrix-bridge-hookshot/tasks/init.yml
+++ b/roles/matrix-bridge-hookshot/tasks/init.yml
@@ -15,12 +15,12 @@
     matrix_synapse_container_extra_arguments: >
       {{ matrix_synapse_container_extra_arguments|default([]) }}
       +
-      ["--mount type=bind,src={{ matrix_hookshot_base_path }}/registration.yaml,dst=/hookshot-registration.yaml,ro"]
+      ["--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.yaml"] }}
+      {{ ["/hookshot-registration.yml"] }}
   when: matrix_hookshot_enabled|bool
 
 - block:
diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
index 0caba20fc..5bd726a4c 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_install.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -31,10 +31,10 @@
   become_user: "{{ matrix_user_username }}"
   when: "not hookshot_passkey_file.stat.exists"
 
-- name: Ensure hookshot config.yaml installed if provided
+- name: Ensure hookshot config.yml installed if provided
   copy:
     content: "{{ matrix_hookshot_configuration|to_nice_yaml }}"
-    dest: "{{ matrix_hookshot_base_path }}/config.yaml"
+    dest: "{{ matrix_hookshot_base_path }}/config.yml"
     mode: 0644
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"
@@ -55,10 +55,10 @@
     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.yaml installed if provided
+- name: Ensure hookshot registration.yml installed if provided
   copy:
     content: "{{ matrix_hookshot_registration|to_nice_yaml }}"
-    dest: "{{ matrix_hookshot_base_path }}/registration.yaml"
+    dest: "{{ matrix_hookshot_base_path }}/registration.yml"
     mode: 0644
     owner: "{{ matrix_user_username }}"
     group: "{{ matrix_user_groupname }}"

From 2b97ab9a518251156a81309c946a8cbe08e5a2d1 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Wed, 12 Jan 2022 00:45:26 +0100
Subject: [PATCH 16/38] fix matrix_hookshot_container_http_host_bind_ports

---
 group_vars/matrix_servers | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index a923437ac..09abdf375 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -671,9 +671,9 @@ matrix_hookshot_container_http_host_bind_ports_defaultmapping:
   - "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: matrix_hookshot_container_http_host_bind_ports_defaultmapping if matrix_nginx_proxy_enabled else []
+matrix_hookshot_container_http_host_bind_ports: "{{ matrix_hookshot_container_http_host_bind_ports_defaultmapping if matrix_nginx_proxy_enabled else [] }}"
 
-matrix_hookshot_provisioning_enabled: "{{ true if matrix_hookshot_provisioning_secret and matrix_dimension_enabled else false}}"
+matrix_hookshot_provisioning_enabled: "{{ true if matrix_hookshot_provisioning_secret and matrix_dimension_enabled else false }}"
 
 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 }}"

From 28c9e7aac2eba461b636ee94dbabcf46131c47ba Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Wed, 12 Jan 2022 01:26:17 +0100
Subject: [PATCH 17/38] fix hookshot commandPrefix jinja2

---
 roles/matrix-bridge-hookshot/templates/config.yml.j2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index 702245c37..2bd6b0e1d 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -32,7 +32,7 @@ github:
     # (Optional) Default options for GitHub connections.
     #
     ignoreHooks: {{ matrix_hookshot_github_ignore_hooks }}
-    commandPrefix: {{ matrix_hookshot_github_command_prefix }}
+    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 }}

From 8498ffd8f7f3f4c2271e49ce17e5d1509fbbd171 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Wed, 12 Jan 2022 01:28:38 +0100
Subject: [PATCH 18/38] name hookshot github private key consistently

---
 docs/configuring-playbook-bridge-hookshot.md         | 2 +-
 roles/matrix-bridge-hookshot/tasks/setup_install.yml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md
index 0dfdfd501..74f9c638f 100644
--- a/docs/configuring-playbook-bridge-hookshot.md
+++ b/docs/configuring-playbook-bridge-hookshot.md
@@ -11,7 +11,7 @@ Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot
 
 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. Before running the playbook, you need to copy that file to `/roles/matrix-bridge-hookshot/files/github-key.pem` so the playbook can install it for you.
+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. Before running the playbook, you need to copy that file to `roles/matrix-bridge-hookshot/files/private-key.pem` so the playbook can install it for you.
 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 the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge.
 
diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
index 5bd726a4c..d07ac26c2 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_install.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -65,7 +65,7 @@
 
 - name: Ensure hookshot github private key file installed if github is enabled
   copy:
-    src: github-key.pem
+    src: private-key.pem
     dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key }}"
     mode: 0600
     owner: "{{ matrix_user_username }}"

From 224633df1dddfced701ea1a58796776b656472da Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Wed, 12 Jan 2022 01:31:46 +0100
Subject: [PATCH 19/38] fix condition for
 matrix_hookshot_container_http_host_bind_ports

---
 group_vars/matrix_servers | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 09abdf375..522d4a186 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -671,7 +671,7 @@ matrix_hookshot_container_http_host_bind_ports_defaultmapping:
   - "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: "{{ matrix_hookshot_container_http_host_bind_ports_defaultmapping if matrix_nginx_proxy_enabled else [] }}"
+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: "{{ true if matrix_hookshot_provisioning_secret and matrix_dimension_enabled else false }}"
 

From 6f32db30638bb2b9ac4064dd34d013352408433a Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Wed, 12 Jan 2022 02:15:37 +0100
Subject: [PATCH 20/38] fix matrix_hookshot_github_oauth_uri

---
 roles/matrix-bridge-hookshot/defaults/main.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index e548e51fa..3063e673c 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -44,7 +44,7 @@ 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: "{{ matrix_server_fqn_matrix }}{{ matrix_hookshot_github_oauth_endpoint }}"
+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'

From 08fe38cf407fdeb397876da6fcd52248cf82497a Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Wed, 12 Jan 2022 13:09:13 +0100
Subject: [PATCH 21/38] add hookshot to nginx wanted services

related 0fb881deb578a37ba9c3fcfc966a2282aa33d3fe
---
 group_vars/matrix_servers | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 522d4a186..18629651f 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -1444,6 +1444,8 @@ matrix_nginx_proxy_systemd_wanted_services_list: |
     (['matrix-ma1sd.service'] if matrix_ma1sd_enabled else [])
     +
     (['matrix-client-element.service'] if matrix_client_element_enabled else [])
+    +
+    (['matrix-hookshot.service'] if matrix_hookshot_enabled else [])
   }}
 
 matrix_ssl_domains_to_obtain_certificates_for: |

From 58b732a84d0d505a73f9ff80b70df94e46e8cf77 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Fri, 14 Jan 2022 19:21:05 +0100
Subject: [PATCH 22/38] support hookshot permissions management

see Half-Shot/matrix-hookshot#167
---
 roles/matrix-bridge-hookshot/defaults/main.yml      | 13 +++++++++++++
 .../matrix-bridge-hookshot/templates/config.yml.j2  |  3 +++
 2 files changed, 16 insertions(+)

diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index 3063e673c..05e7c5a0a 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -108,6 +108,19 @@ matrix_hookshot_provisioning_secret: ''
 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'
diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index 2bd6b0e1d..8be3b1d6d 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -100,6 +100,9 @@ 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.

From df074151cdc9bc5455c754b4283b90cb3648b1bc Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Fri, 14 Jan 2022 19:24:37 +0100
Subject: [PATCH 23/38] update default hookshot webhook mxid prefix

---
 roles/matrix-bridge-hookshot/defaults/main.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index 05e7c5a0a..1982a5f32 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -86,7 +86,8 @@ matrix_hookshot_generic_enabled: true
 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
-matrix_hookshot_generic_user_id_prefix: 'webhooks_'
+# 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

From 5d07f14235904abbb432e3f9f73474d72f779fd5 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 23 Jan 2022 15:11:25 +0100
Subject: [PATCH 24/38] install openssl for hookshot

using b33ea48
---
 roles/matrix-bridge-hookshot/tasks/setup_install.yml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
index d07ac26c2..22d3f0254 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_install.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -1,7 +1,6 @@
 ---
 
-#  (#1510)
-# - import_tasks: "{{ role_path }}/../matrix-base/tasks/util/ensure_openssl_installed.yml"
+- import_tasks: "{{ role_path }}/../matrix-base/tasks/util/ensure_openssl_installed.yml"
 
 - name: Ensure hookshot image is pulled
   docker_image:

From a1a5b16185deaca215e1352014c9e2188ae18955 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 23 Jan 2022 16:10:25 +0100
Subject: [PATCH 25/38] update hookshot private key installation method

---
 docs/configuring-playbook-bridge-hookshot.md  | 27 ++++++++++++++++---
 .../matrix-bridge-hookshot/defaults/main.yml  | 10 +++++--
 .../tasks/setup_install.yml                   |  8 +++---
 3 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md
index 74f9c638f..53f19db2d 100644
--- a/docs/configuring-playbook-bridge-hookshot.md
+++ b/docs/configuring-playbook-bridge-hookshot.md
@@ -11,13 +11,34 @@ Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot
 
 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. Before running the playbook, you need to copy that file to `roles/matrix-bridge-hookshot/files/private-key.pem` so the playbook can install it for you.
+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 the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge.
 
+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`.
 
-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).
+### Metrics
 
-Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in `/roles/matrix-bridge-hookshot/defaults/main.yml` for how to use them.
+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).
diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index 1982a5f32..a0ecb6ff0 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -35,8 +35,14 @@ matrix_hookshot_webhook_endpoint: "{{ matrix_hookshot_public_endpoint }}/webhook
 # https://half-shot.github.io/matrix-hookshot/setup/github.html
 matrix_hookshot_github_enabled: false
 matrix_hookshot_github_appid: ''
-# manually copy the generated and downloaded GitHub private key to roles/matrix-bridge-hookshot/files/private-key.pem
-matrix_hookshot_github_private_key: 'private-key.pem'
+# 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)
diff --git a/roles/matrix-bridge-hookshot/tasks/setup_install.yml b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
index 22d3f0254..059dd7b5b 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_install.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_install.yml
@@ -64,12 +64,12 @@
 
 - name: Ensure hookshot github private key file installed if github is enabled
   copy:
-    src: private-key.pem
-    dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key }}"
-    mode: 0600
+    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"
+  when: "{{ matrix_hookshot_github_enabled|bool and matrix_hookshot_github_private_key|length }}"
 
 - name: Ensure matrix-hookshot.service installed
   template:

From 4de2b4bf3b7b3f3e5077bdbf57607e086c449898 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 23 Jan 2022 17:05:40 +0100
Subject: [PATCH 26/38] update hookshot docs

---
 docs/configuring-playbook-bridge-hookshot.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md
index 53f19db2d..4e9147916 100644
--- a/docs/configuring-playbook-bridge-hookshot.md
+++ b/docs/configuring-playbook-bridge-hookshot.md
@@ -13,7 +13,7 @@ Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot
 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 the [official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge.
+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.
 

From c264d670e81256f50da5550e5d40b9c9da495cfb Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 17:41:51 +0100
Subject: [PATCH 27/38] update hookshot config to generic hs variables

---
 group_vars/matrix_servers | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 39940a858..4d7518cc4 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -671,13 +671,13 @@ matrix_heisenbridge_systemd_wanted_services_list: |
 # We don't enable bridges by default.
 matrix_hookshot_enabled: false
 
-matrix_hookshot_appservice_token: "{{ '%s' | format(matrix_synapse_macaroon_secret_key) | password_hash('sha512', 'hookshot.as.tok') | to_uuid }}"
+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_synapse_macaroon_secret_key) | password_hash('sha512', 'hookshot.hs.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-synapse.service'] if matrix_synapse_enabled else [])
+    (['matrix-' + matrix_homesever_implementation + '.service'])
     +
     (['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
   }}

From 54d8d0ec381d6980f77b81d1c5c890cd45b618c4 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 17:43:08 +0100
Subject: [PATCH 28/38] simplify hookshot conditional for readability

---
 group_vars/matrix_servers | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 4d7518cc4..f66cb74f8 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -690,7 +690,7 @@ matrix_hookshot_container_http_host_bind_ports_defaultmapping:
 
 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: "{{ true if matrix_hookshot_provisioning_secret and matrix_dimension_enabled else false }}"
+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 }}"

From 99802bc143354f5c0cae51607b714daba5c92c7e Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 17:44:22 +0100
Subject: [PATCH 29/38] escape hookshot variables using to_json

---
 .../templates/config.yml.j2                    | 18 +++++++++---------
 .../templates/registration.yml.j2              |  4 ++--
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index 8be3b1d6d..ce979b06d 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -19,13 +19,13 @@ github:
   webhook:
     # Webhook settings for the GitHub app.
     #
-    secret: {{ matrix_hookshot_github_secret }}
+    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 }}
+    client_secret: {{ matrix_hookshot_github_oauth_secret|to_json }}
     redirect_uri: {{ matrix_hookshot_github_oauth_uri }}
 {% endif %}
   defaultOptions:
@@ -45,18 +45,18 @@ gitlab:
   instances:
     {{ matrix_hookshot_gitlab_instances }}
   webhook:
-    secret: {{ matrix_hookshot_gitlab_secret }}
+    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 }}
+    secret: {{ matrix_hookshot_jira_secret|to_json }}
 {% if matrix_hookshot_jira_oauth_enabled %}
   oauth:
-    client_id: {{ matrix_hookshot_jira_oauth_id }}
-    client_secret: {{ matrix_hookshot_jira_oauth_secret }}
+    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 %}
@@ -67,7 +67,7 @@ generic:
   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 }}
+  userIdPrefix: {{ matrix_hookshot_generic_user_id_prefix|to_json }}
 {% endif %}
 {% if matrix_hookshot_figma_enabled %}
 figma:
@@ -80,7 +80,7 @@ figma:
 provisioning:
   # (Optional) Provisioning API for integration managers
   #
-  secret: {{ matrix_hookshot_provisioning_secret }}
+  secret: {{ matrix_hookshot_provisioning_secret|to_json }}
 {% endif %}
 passFile:
   # A passkey used to encrypt tokens stored inside the bridge.
@@ -90,7 +90,7 @@ passFile:
 bot:
   # (Optional) Define profile information for the bot user
   #
-  displayname: {{ matrix_hookshot_bot_displayname }}
+  displayname: {{ matrix_hookshot_bot_displayname|to_json }}
   avatar: {{ matrix_hookshot_bot_avatar }}
 metrics:
   # (Optional) Prometheus metrics support
diff --git a/roles/matrix-bridge-hookshot/templates/registration.yml.j2 b/roles/matrix-bridge-hookshot/templates/registration.yml.j2
index e86426c80..ced3bd77e 100644
--- a/roles/matrix-bridge-hookshot/templates/registration.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/registration.yml.j2
@@ -1,7 +1,7 @@
 #jinja2: lstrip_blocks: "True"
 id: matrix-hookshot # This can be anything, but must be unique within your homeserver
-as_token: {{ matrix_hookshot_appservice_token }} # This again can be a random string
-hs_token: {{ matrix_hookshot_homeserver_token }} # ..as can this
+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:

From a3c84f78ca9c65a3d598b8486d96b0e0b5b328ed Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 17:44:59 +0100
Subject: [PATCH 30/38] update hookshot.service to ExecStopPost

---
 .../templates/systemd/matrix-hookshot.service.j2              | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2 b/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
index 16ff05920..5fa2278c8 100644
--- a/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
+++ b/roles/matrix-bridge-hookshot/templates/systemd/matrix-hookshot.service.j2
@@ -30,8 +30,8 @@ ExecStart={{ matrix_host_command_docker }} run --rm --name {{ matrix_hookshot_co
           {% endfor %}
           {{ matrix_hookshot_docker_image }}
 
-ExecStop=-{{ matrix_host_command_docker }} kill {{ matrix_hookshot_container_url }}
-ExecStop=-{{ matrix_host_command_docker }} rm {{ matrix_hookshot_container_url }}
+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 }}

From 29d0b277f4e9dd42042ebe435209eed3f230d578 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 17:45:28 +0100
Subject: [PATCH 31/38] fix hookshot missing figma config variable

---
 roles/matrix-bridge-hookshot/templates/config.yml.j2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index ce979b06d..d942eb83e 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -73,7 +73,7 @@ generic:
 figma:
   # (Optional) Configure this to enable Figma support
   #
-  publicUrl: https://example.com/hookshot/
+  publicUrl: {{ matrix_hookshot_figma_publicUrl }}
   instances: {{ matrix_hookshot_figma_instances }}
 {% endif %}
 {% if matrix_hookshot_provisioning_enabled %}

From f47bfdfb4f80c5ffc8bb1c3080f71c65bbb4ce17 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 17:46:01 +0100
Subject: [PATCH 32/38] remove hookshot uninstall comments based on feedback

---
 roles/matrix-bridge-hookshot/tasks/setup_uninstall.yml | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/roles/matrix-bridge-hookshot/tasks/setup_uninstall.yml b/roles/matrix-bridge-hookshot/tasks/setup_uninstall.yml
index 52e126e9d..89ab01b46 100644
--- a/roles/matrix-bridge-hookshot/tasks/setup_uninstall.yml
+++ b/roles/matrix-bridge-hookshot/tasks/setup_uninstall.yml
@@ -23,6 +23,3 @@
   service:
     daemon_reload: yes
   when: "matrix_hookshot_service_stat.stat.exists"
-
-# remove base_path?
-# remove docker image?

From 4477711e793445e5acbe9baf1516a57b6f374186 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 17:46:40 +0100
Subject: [PATCH 33/38] add some hookshot config validation

---
 roles/matrix-bridge-hookshot/tasks/main.yml   |  6 ++
 .../tasks/validate_config.yml                 | 59 +++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 roles/matrix-bridge-hookshot/tasks/validate_config.yml

diff --git a/roles/matrix-bridge-hookshot/tasks/main.yml b/roles/matrix-bridge-hookshot/tasks/main.yml
index 52d90aa1e..85ab25890 100644
--- a/roles/matrix-bridge-hookshot/tasks/main.yml
+++ b/roles/matrix-bridge-hookshot/tasks/main.yml
@@ -2,6 +2,12 @@
   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:
diff --git a/roles/matrix-bridge-hookshot/tasks/validate_config.yml b/roles/matrix-bridge-hookshot/tasks/validate_config.yml
new file mode 100644
index 000000000..645f0aa80
--- /dev/null
+++ b/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_id"
+    - "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"

From f136c1fb8f8e088e915b31eb3f4e49bf159c71c2 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 18:53:57 +0100
Subject: [PATCH 34/38] fixup! add some hookshot config validation

---
 roles/matrix-bridge-hookshot/tasks/validate_config.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-hookshot/tasks/validate_config.yml b/roles/matrix-bridge-hookshot/tasks/validate_config.yml
index 645f0aa80..5da8809ee 100644
--- a/roles/matrix-bridge-hookshot/tasks/validate_config.yml
+++ b/roles/matrix-bridge-hookshot/tasks/validate_config.yml
@@ -15,7 +15,7 @@
       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_id"
+    - "matrix_hookshot_github_appid"
     - "matrix_hookshot_github_secret"
 
 - name: Fail if required GitHub OAuth settings not defined

From 5300dc7a8bf957d059f88a68f431f6ba80c95654 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 19:05:49 +0100
Subject: [PATCH 35/38] update hookshot/defaults/main.yml comments

---
 .../matrix-bridge-hookshot/defaults/main.yml  | 47 ++++++++++---------
 1 file changed, 24 insertions(+), 23 deletions(-)

diff --git a/roles/matrix-bridge-hookshot/defaults/main.yml b/roles/matrix-bridge-hookshot/defaults/main.yml
index a0ecb6ff0..e32dba3bf 100644
--- a/roles/matrix-bridge-hookshot/defaults/main.yml
+++ b/roles/matrix-bridge-hookshot/defaults/main.yml
@@ -14,44 +14,44 @@ 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.
+# 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
+# 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.
+# 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.
+# 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
+# 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:
+# 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.
+# 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)
+# 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"
+# 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
+# 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
@@ -61,7 +61,7 @@ matrix_hookshot_github_excluding_labels: ''
 
 
 matrix_hookshot_gitlab_enabled: true
-# optionally add your instances, e.g.
+# Optionally add your instances, e.g.
 # matrix_hookshot_gitlab_instances:
 #   gitlab.com:
 #     url: https://gitlab.com
@@ -71,36 +71,36 @@ 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
+# 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
+# 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"
+# 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
+# No need to change these
 matrix_hookshot_generic_enabled: true
-# default value of matrix_hookshot_generic_endpoint: "/hookshot/webhooks"
+# 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
+# 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"
+# 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:
+# To bridge figma webhooks, you need to configure one of multiple instances like this:
 # matrix_hookshot_figma_instances:
 #   your-instance:
 #       teamId: your-team-id
@@ -108,10 +108,10 @@ matrix_hookshot_figma_publicUrl: "{{ matrix_server_fqn_matrix }}{{ matrix_hooksh
 #       passcode: your-webhook-passcode
 
 
-# there is no need to edit ports. use matrix_hookshot_container_http_host_bind_ports below to expose ports instead.
+# 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
+# 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"
 
@@ -152,6 +152,7 @@ matrix_hookshot_systemd_wanted_services_list: []
 # 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: ''
 

From 99cf6adf95f04d3c9957c5b90f7e378833605af7 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 19:21:26 +0100
Subject: [PATCH 36/38] fixup! update hookshot private key installation method

---
 roles/matrix-bridge-hookshot/templates/config.yml.j2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index d942eb83e..f58201f9e 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -15,7 +15,7 @@ github:
     # Authentication for the GitHub App.
     #
     id: {{ matrix_hookshot_github_appid }}
-    privateKeyFile: /data/{{ matrix_hookshot_github_private_key }}
+    privateKeyFile: /data/{{ matrix_hookshot_github_private_key_file }}
   webhook:
     # Webhook settings for the GitHub app.
     #

From 51baa40effa4dc1a09006068bed097648b0357a3 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 19:28:40 +0100
Subject: [PATCH 37/38] fixup! escape hookshot variables using to_json

---
 roles/matrix-bridge-hookshot/templates/config.yml.j2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/roles/matrix-bridge-hookshot/templates/config.yml.j2 b/roles/matrix-bridge-hookshot/templates/config.yml.j2
index f58201f9e..fc04c7559 100644
--- a/roles/matrix-bridge-hookshot/templates/config.yml.j2
+++ b/roles/matrix-bridge-hookshot/templates/config.yml.j2
@@ -90,7 +90,7 @@ passFile:
 bot:
   # (Optional) Define profile information for the bot user
   #
-  displayname: {{ matrix_hookshot_bot_displayname|to_json }}
+  displayname: {{ matrix_hookshot_bot_displayname }}
   avatar: {{ matrix_hookshot_bot_avatar }}
 metrics:
   # (Optional) Prometheus metrics support

From 39d9ef43e9d1053cb691e20b4319c9600ec44141 Mon Sep 17 00:00:00 2001
From: HarHarLinks <kim.brose@rwth-aachen.de>
Date: Sun, 30 Jan 2022 19:32:09 +0100
Subject: [PATCH 38/38] fixup! update hookshot config to generic hs variables

---
 group_vars/matrix_servers | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index 201159ecd..3ab255cfd 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -677,7 +677,7 @@ matrix_hookshot_homeserver_token: "{{ '%s' | format(matrix_homeserver_generic_se
 
 matrix_hookshot_systemd_wanted_services_list: |
   {{
-    (['matrix-' + matrix_homesever_implementation + '.service'])
+    (['matrix-' + matrix_homeserver_implementation + '.service'])
     +
     (['matrix-nginx-proxy.service'] if matrix_nginx_proxy_enabled else [])
   }}