Setting up GitHub

GitHub App

This bridge requires a GitHub App. You will need to create one.

Webhook

The Webhook URL should point to the public address of your hookshot instance, at the / path. You MUST also provide a secret, which should match the github.webhook.secret value in your config.

Permissions

You will need to enable the following permissions:

  • Repository
    • Actions (read)
    • Contents (read)
    • Discussions (read & write)
    • Issues (read & write)
    • Metadata
    • Projects (read & write)
    • Pull requests (read & write)
  • Organisation
    • Team Discussions (read & write)

Hookshot handles the following webhook event types:

  • Commit comment
  • Create
  • Delete
  • Discussion
  • Discussion comment
  • Issue comment
  • Issues
  • Project
  • Project card
  • Project column
  • Pull request
  • Pull request review
  • Pull request review comment
  • Push
  • Release
  • Repository
  • Workflow run

You can disable any of these to disable the events being handled in Hookshot.

Once you have set up your app, you can move onto configuring the bridge:

Bridge Configuration

The GitHub service requires a few connection options.

github:
  enterpriseUrl: "https://your-enterprise-address.com"
  auth:
    id: 123
    privateKeyFile: github-key.pem
  webhook:
    secret: secrettoken
  oauth:
    client_id: foo
    client_secret: bar
    redirect_uri: https://example.com/oauth/
  defaultOptions:
    showIssueRoomLink: false

If you are using an on-premise / enterprise edition of GitHub, you need provide the base URL in enterpriseUrl. You do not need to specify the /api/... path in the URL.

In the auth section, you will need to supply the App ID given in your GitHub App page. The privateKeyFile can be generated by clicking "Generate a private key" under the Private keys section on the GitHub app page. Docker users should store this file alongside config.yml and provide the path /data/github-key.pem.

The webhook section takes a secret, which is Webhook secret on the GitHub App page.

The oauth section should include both the Client ID and Client Secret on the GitHub App page. The redirect_uri value must be the public path to /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/oauth. This value MUST exactly match the Callback URL on the GitHub App page.

defaultOptions allows you to set some defaults for room connections. Options listed on this page are supported.

Next steps

If you have followed these steps correctly, GitHub should now be configured with hookshot đŸĨŗ.

You can now follow the guide on authenticating with GitHub, and then bridging a room