| @@ -1,22 +1,22 @@ | |||
| # Setting up Hookshot (optional) | |||
| The playbook can install and configure [matrix-hookshot](https://github.com/Half-Shot/matrix-hookshot) for you. | |||
| The playbook can install and configure [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) for you. | |||
| Hookshot can bridge [Webhooks](https://en.wikipedia.org/wiki/Webhook) from software project management services such as GitHub, GitLab, JIRA, and Figma, as well as generic webhooks. | |||
| See the project's [documentation](https://half-shot.github.io/matrix-hookshot/hookshot.html) to learn what it does in detail and why it might be useful to you. | |||
| See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/hookshot.html) to learn what it does in detail and why it might be useful to you. | |||
| Note: the playbook also supports [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), which however is soon to be archived by its author and to be replaced by hookshot. | |||
| ## Setup Instructions | |||
| Refer to the [official instructions](https://half-shot.github.io/matrix-hookshot/setup.html) to learn what the individual options do. | |||
| Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/setup.html) to learn what the individual options do. | |||
| 1. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](/roles/matrix-bridge-hookshot/defaults/main.yml) as required. | |||
| 2. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma). | |||
| 3. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-matrix-aux-role) explained below. | |||
| 4. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`. | |||
| 5. Refer to [Hookshot's official instructions](https://half-shot.github.io/matrix-hookshot/usage.html) to start using the bridge. Note that the different listeners are bound to certain paths (see `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles/matrix-bridge-hookshot/tasks/init.yml)): by default webhooks root is `/hookshot/webhooks/`. | |||
| 5. Refer to [Hookshot's official instructions](https://matrix-org.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. | |||
| @@ -1,7 +1,7 @@ | |||
| --- | |||
| # A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA. | |||
| # https://github.com/Half-Shot/matrix-hookshot | |||
| # https://github.com/matrix-org/matrix-hookshot | |||
| matrix_hookshot_enabled: true | |||
| @@ -34,7 +34,7 @@ matrix_hookshot_webhook_endpoint: "{{ matrix_hookshot_public_endpoint }}/webhook | |||
| # 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 | |||
| # https://matrix-org.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: | |||
| @@ -53,7 +53,7 @@ matrix_hookshot_github_oauth_secret: '' # "Client Secret" on the GitHub App pag | |||
| # 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://matrix-org.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 | |||
| @@ -78,7 +78,7 @@ 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://matrix-org.github.io/matrix-hookshot/setup/jira.html#jira-oauth | |||
| matrix_hookshot_jira_secret: '' | |||
| matrix_hookshot_jira_oauth_enabled: false | |||
| matrix_hookshot_jira_oauth_id: '' | |||
| @@ -117,7 +117,7 @@ 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 | |||
| # You can configure access to the bridge as documented here https://matrix-org.github.io/matrix-hookshot/setup.html#permissions | |||
| # When empty, the default permissions are applied. | |||
| # Example: | |||
| # matrix_hookshot_permissions: | |||