JIRA

Adding a webhook to a JIRA Instance

This should be done for the JIRA instance you wish to bridge. The setup steps are the same for both On-Prem and Cloud.

You need to go to the WebHooks configuration page under Settings > System. Note that this may require administrative access to the JIRA instance.

Next, add a webhook that points to / on the public webhooks address for hookshot. You should also include a secret value by appending ?secret=your-webhook-secret. The secret value can be anything, but should be reasonably secure and should also be stored in the config.yml file.

Ensure that you enable all the events that you wish to be bridged.

Configuration

You can now set some configuration in the bridge config.yml:

jira:
  webhook:
    secret: some-secret
  oauth:
    ... # See below

You can omit the oauth section if you are not planning to allow users to log in and use interactive features (i.e. webhook only mode).

Connecting Matrix users to JIRA

Hookshot allows Matrix users to directly interact with JIRA through the bridge. The setup process differs depending on whether you are running a on-premise/enterprise instance or using Atlassian's cloud service.

JIRA OAuth for Cloud

You will need a Atlassian account with the ability to use the developer tools in order to create the app.

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

You can now set some configuration in the bridge config.yml

jira:
  webhook:
    # A secret string generated by you.
    secret: some-secret
  oauth:
    client_id: your-client-id
    client_secret: your-client-secret
    redirect_uri: https://example.com/hookshot/jira/oauth

The redirect_uri value must be the public path to /jira/oauth on the webhooks path. E.g. if your load balancer points https://example.com/hookshot to the bridge webhooks listener, you should use the path https://example.com/hookshot/jira/oauth. This value MUST exactly match the Callback URL on the JIRA integration page page.

JIRA for On-Premise (Datacenter)

These instructions are written for Jira Datacenter 8.x. These instructions use openssl to generate certificates, so users on non-Unix systems will need to find an alternative way to generate these certificates.

To begin, configure your config.yml:

jira:
  url: https://yourjirainstance.com # The location of your jira instance.
  webhook:
    # A secret string generated by you.
    secret: Ieph7iecheiThoo1othaineewieSh1koh2chainohtooyoh4waht1oetoaSoh6oh
  oauth:
    # Another secret key generated by you.
    consumerKey: secret-consumer-key
    # Path to a private key. Generate this with `openssl genrsa -out jira_privatekey.pem 4096`
    privateKey: jira_privatekey.pem
    # The path to your webhooks listener on the "/jira/oauth" path.
    redirect_uri: http://localhost:5065/jira/oauth

To start with, set up your JIRA instance to support OAuth.

Open the Administration page for your JIRA instance.
Click Applications.
Click Application Links.
1. Newer versions of JIRA need you to click "Create link"
In the text box, enter "https://github.com/Half-Shot/matrix-hookshot". Jira will complain but click Continue.
Fill in the details:
1. The Application Name can be anything, but for simplicty we usually use matrix-hookshot
2. The Application Type should be Generic Application
3. The Consumer key, and shared secret can be any string, they are not used.
4. The URLs can be any URL, they are not used (e.g. https://example.com)
5. Ensure you enable Create incoming link
6. Click Continue
On the next step:
1. Enter your consumerKey from the config file above.
2. The consumerName can be anything, but will be visible to users of your app. You could use something like Matrix, Hookshot or anything else.
3. The publicKey can be generated by running openssl rsa -in jira_privatekey.pem -pubout on the key you created earlier.
Congratulations, you now have OAuth set up.

Next steps

If you have followed these steps correctly, JIRA should now be configured with hookshot 🥳.

You can now follow the guide on authenticating with JIRA.

Matrix Hookshot