Setting up GitLab, GitHub, JIRA and Webhooks Integrations With the Installer
Enterprise On-Premise, our GitLab, GitHub, and JIRA integrations
are provided by the hookshot package. This documentation explains how to
configure the installer to install hookshot and then how to interact with
hookshot once installed.
Configuring Hookshot with the Installer
Copy sample file from config-sample/hookshot/hookshot.yml in
installer directory to ~/.element-onpremise-config/hookshot Edit
file withthe following values : logging_level : Thelogging level
hookshot_fqdn : The adress ofhookshot webhook fqdn. It should match something like hookshot.<fqdn.tld> passkey : The name of the local key file. Itcan be generated using openssl - openssl genrsa -out key.pem 4096 provisioning_secret : The provisioning secret used with integration managers. Necessary for integration with integrator. bot_display_name : The name of hookshot bot bot_avatar : An mxc:// uri to the hookshot bot avatar image. verify_tls : Optional. If doing a POC with self-signed certificates, set this to 0. Defaults to 1. disallowed_ip_ranges : Optional. A list of IP ranges to not allow connectivity to. For more information on this, please see: https://ems-docs.element.io/books/ems-knowledge-base/page/hookshot-fails-to-display-configuration-widget
Restart the install script Enabling GitHub Integration On GitHub This bridge requires a GitHub App . Youwill need to create one. On the callback URL, setthe following one : https://<hookshot_fqdn>/oauth and enable Request user authorization( OAuth) during installation On the webhook URL, set the following one :
https://<hookshot_fqdn>/ don't forget the ending / ) For the webhook secret,you can generate one using pwgen 32 1 to generate one for example. Keep it somewhere safe, you'll need to to configure the bridge. Set the following permissions for the webhook : Repository Actions (read) Contents (read) Discussions (read & write) Issues (read & write) Metadata Projects (read & write) Pull requests (read & write) Organisation Team Discussions (read & write) Install the App On the installation Copy samplefile from config-sample/hookshot/github.yml in the installer directory to ~/.element-onpremise-config/hookshot Edit the file with the following values : github_auth_id : The AppID given in your github app page github_key_file : The key file received via the Generate a private key button under Private keys section of the github app page. github_webhook_secret : The webhook secret configured in the app. github_oauth_client_id : The OAuth ClientID of the github app page. github_oauth_client_secret : The OAuth Client Secret of the github app page. github_oauth_default_options A mapping to enable special oauth options. Restart the install script In Element's room Start a private conversation with the bot Type github login Follow the link to connect the bot to the configured app As an administrator of the room, invite the hookshot bot Promote the bot to a Moderator/Admin If you have setup Integrator, youcan use the integration managerto add a bridge to github Enabling GitLab integration On GitLab Add a webhook underthe group or the repository you are targeting On the webhook URL, set the following one : https://<hookshot_fqdn>/ For the webhook secret, you can generate one using pwgen 32 1 to generate one for example. Keep it somewhere safe, you'll need to to configure the bridge. You should add the events
you wish to
currently supports: Push events Tag events Issues events Merge request events Releases events
installation Copy sample file from
config-sample/hookshot/gitlab.yml installer directoryto ~/.element-onpremise-config/hookshot Editthe file with
values : gitlab_instances : A mapping ofthe GitLab servers
gitlab_webhook_secret : The secret configured inthe webhook.
In Element's room Start a private conversation withthe bot Type
to connect to
gitlab personaltoken instancename personaltoken GitLab where instancename is one of the mappings of the GitLab servers (git.example.org) and personaltoken, a token generated from the GitLab admin UI As an administrator of the room, invite the hookshot bot Run the command !hookshot gitlab project https://mydomain/my/project to bridge a project to the room Type !gl help to list supported commands Enabling JIRA integration On JIRA This should be done for all JIRA organisations you wish to bridge. The steps may differ for SaaS and on-prem, but you need to go to the webhooks configuration page under Settings > System > Webhooks. It should point to https://<hookshot_fqdn>/?secret=<jira_webhook_secret> For the webhook secret, you can generate one using pwgen 32 1 to generate one for example. Keep it somewhere safe, you'll need to to configure the bridge.
The JIRA service currently only supports atlassian.com (JIRA SaaS) when handling user authentication. Support for on-prem deployments is hoping to land soon.
- You'll first need to head to https://developer.atlassian.com/console/myapps/create-3lo-app/ to create a "OAuth 2.0 (3LO)" integration.
- Once named and created, you will need to:
- Enable the User REST, JIRA Platform REST and User Identity APIs under Permissions.
- Use rotating tokens under Authorisation.
- Set a callback url. This will be the public URL to hookshot with a path of /jira/oauth.
- Copy the client ID and Secret from Settings
installation Copy sample file from config-sample/hookshot/jira.yml Edit
following values :
jira_webhook_secret : The webhook secret configured
jira_oauth_client_id : If Oauth
enabled, it should point
Jira's App page. Else,you can keep it empty. jira_oauth_client_secret : If Oauth is enabled, it should pointto the Client secret in Jira's App page. Else, you can keep it empty.
In Element's room
administrator of the room,invite the hookshot bot If
setup Integrator,you can use the integration managerto add a bridge to JIRA. There is currently a limitation - it only works for public rooms. Enabling generic webhooks integration