hookshot role groundwork

This commit is contained in:
HarHarLinks 2022-01-03 21:22:42 +01:00
parent 948c411106
commit 621251c1e5
10 changed files with 515 additions and 0 deletions

View file

@ -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.

View file

@ -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 # matrix-bridge-mx-puppet-skype

View file

@ -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) }}"

View file

@ -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"

View file

@ -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

View file

@ -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

View file

@ -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?

View file

@ -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

View file

@ -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

View file

@ -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