hookshot/docs/setup/jira.md

# 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`:

```yaml
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:
  1. Enable the User REST, Jira Platform REST and User Identity APIs under Permissions.
  2. Use rotating tokens under Authorisation.
  3. Set a callback url. This will be the public URL to hookshot with a path of `/jira/oauth`.
  4. Copy the client ID and Secret from Settings

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

```yaml
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`:


```yaml
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.


1. Open the **Administration** page for your JIRA instance.
2. Click **Applications**.
3. Click **Application Links**.
   1. Newer versions of JIRA need you to click "Create link"
4. In the text box, enter "https://github.com/Half-Shot/matrix-hookshot". Jira will complain but click **Continue**.
5. 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**
6. 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.
7. 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](../usage/auth.md#jira).