Add documentation on various things (#90)

* Add details on webhooks

* More doc things

* More docs

* More documentation changes

* Tidy tidy

* Lots more documentation

* Support defaults for all GitHub configuration options

* Add metrics changes

* s/Added/Add

Cargo.toml

@@ -18,5 +18,6 @@ rgb = "0"
 md-5 = "0.8.0"
 hex = "0.4.3"
 
+
 [build-dependencies]
-napi-build = "1"
+napi-build = "1"

README.md

@@ -8,60 +8,25 @@ matrix-hookshot
 
 A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA.
 
+## Featureset
+
+This bridge bridges:
+
+- GitHub
+  - Webhooks (new issues, pull requests, releases etc)
+  - Commands (create issues, assign issues, start workflows etc)
+- GitLab
+  - Webhooks (new issues, merge requests etc)
+  - Commands
+- Jira
+  - Webhooks (new issues, issue changes)
+  - Commands (create new issues)
+- Generic webhooks
+  - Webhooks (via GET, PUT or POST with optional transformation functions)
+
 ## Setup
 
-This bridge requires at least Node 12, and Rust installed. If you do not have rust, https://rustup.rs/ is the quickest way to get it.
-
-To set up the bridge, simply clone this repository.
-
-` git clone git@github.com:Half-Shot/matrix-hookshot.git`
-
-then you will need to install the dependencies
-
-```sh
-cd matrix-hookshot
-yarn
-```
-
-Then you will need to copy the `config.sample.yml` to a new file called `config.yml`. You should fill this in. Pay **close** attention to settings like `passkey` which are required for the bridge to function.
-
-For the GitHub tokens, you will need to create a new [GitHub App](https://github.com/settings/apps/new)
-
-You will need to allow access to your bridge instance via a public URL, and fill in the Webhook URL option on GitHub. You will need to also generate a secret key which can be anything, but should be long and unique.
-
-Additionally, you will need to setup some permissions in "Permissions & events".
-
-Largely, these need to be:
-
-- Repository contents: "Read & Write"
-- Issues: "Read & Write"
-- Pull-requests: "Read & Write"
-
-You will also need to subscribe to, at a minimum:
-
-- Issues
-- Label
-- Issue comment
-- Pull request
-- Pull request review
-- Pull request review comment
-
-Once that is setup, you will need to create a registration file for the bridge. Copy `registration.sample.yml` into `registration.yml` and fill in. You are nearly done! Copy or link the registration.yml file to your homeserver in some way, and reconfigure your homeserver to use it. Ensure you have restarted your homeserver if needed (Synapse needs this).
-
-## Running
-
-You can run `npm run start:app` to start the app.
-
-
-## Running in multi-process mode.
-
-If you are running as a non-monolith, then you should also run `npm run start:webhooks`. In the case of the latter, ensure a Redis instance is running. 
-
-You can quickly setup a redis by either installing it from your system package manager, or just running
-
-`docker run --name github-bridge-redis -p 6379:6379 -d redis`
-
-in Docker.
+[See the setup guide](https://half-shot.github.io/matrix-hookshot/setup.html)
 
 ## Documentation
 
@@ -76,4 +41,4 @@ sensible-browser book/index.html
 
 ## Contact
 
-TODO...
+TODO...

book.toml

@@ -4,3 +4,21 @@ language = "en"
 multilingual = false
 src = "docs"
 title = "Matrix Hookshot"
+
+[build]
+# Prevent markdown pages from being automatically generated when they're
+# linked to in SUMMARY.md
+create-missing = false
+
+
+[output.html]
+# The URL visitors will be directed to when they try to edit a page
+edit-url-template = "https://github.com/half-shot/matrix-hookshot/edit/main/{path}"
+
+# The source code URL of the repository
+git-repository-url = "https://github.com/half-shot/matrix-hookshot"
+
+
+additional-css = [
+    "docs/_site/style.css"
+]

changelog.d/90.doc

@@ -0,0 +1 @@
+Add documentation for most functionality in the bridge.

docs/SUMMARY.md

@@ -1,10 +1,18 @@
 # Summary
 
 - [Hookshot](./hookshot.md)
-- [Features](./features.md)
 - [Setup](./setup.md)
+  - [Sample Configuration](./setup/sample-configuration.md)
   - [GitHub](./setup/github.md)
   - [GitLab](./setup/gitlab.md)
   - [JIRA](./setup/jira.md)
   - [Webhooks](./setup/webhooks.md)
+- [Usage](./usage.md)
+  - [Dynamic Rooms](./usage/dynamic_rooms.md)
+  - [Authenticating](./usage/auth.md)
+  - [Room Configuration](./usage/room_configuration.md)
+    - [GitHub Repo](./usage/room_configuration/github_repo.md)
 - [Metrics](./metrics.md)
+- [Advanced](./advanced/provisioning.md)
+  - [Provisioning](./advanced/provisioning.md)
+  - [Workers](./advanced/workers.md)

docs/_site/style.css

@@ -0,0 +1,25 @@
+.notice {
+    border: 2px solid #0098d4;
+    border-left-width: 2px;
+    border-left-width: 5px;
+    background: #e5f5fb;
+    padding: 10px 20px;
+}
+
+.notice::before {
+    content: "INFO: ";
+    font-weight: 700;
+}
+
+.warning {
+    border: 2px solid #dda02f;
+    border-left-width: 2px;
+    border-left-width: 5px;
+    background: #fdcd74;
+    padding: 10px 20px;
+}
+
+.warning::before {
+    content: "WARNING: ";
+    font-weight: 700;
+}

docs/advanced/provisioning.md

@@ -0,0 +1,6 @@
+Provisioning
+============
+
+This section is not complete yet for end users. For developers, you can read the documentation for the API below:
+
+{{#include ../../src/provisioning/api.md}}

docs/advanced/workers.md

@@ -0,0 +1,33 @@
+Workers
+=======
+
+Hookshot supports running in a worker configuration, using Redis as the middleman process to handle traffic between processes.
+
+<section class="warning">
+This feature is <b>experimental</b> and should only be used when you are reaching natural limits in the monolith process.
+</section>
+
+## Running in multi-process mode
+
+You must first have a working redis instance somewhere which can talk between processes. For example, in Docker you can run:
+
+`docker run --name github-bridge-redis -p 6379:6379 -d redis`.
+
+
+The processes should all share the same config, which should contain the correct config enable redis:
+
+```yaml
+queue:
+  monolithic: true
+  port: 6379
+  host: github-bridge-redis
+```
+
+Once that is done, you can simply start the processes by name using yarn:
+```
+yarn start:webhooks
+yarn start:matrixsender 
+yarn start:app
+```
+
+Be aware that you will need to start all worker types when running in worker mode, as the service does not allow a hybrid worker approach.

docs/auth.md

@@ -0,0 +1,7 @@
+# Authenticating
+
+## GitHub
+
+### Personal Access Token
+
+### OAuth2

docs/features.md

@@ -1 +0,0 @@
-# Features

docs/hookshot.md

@@ -1 +1 @@
-# Chapter 1
+{{#include ../README.md}}

docs/metrics.md

@@ -1,7 +1,16 @@
 Prometheus Metrics
 ==================
 
-Below is the generated list of prometheus metrics for hookshot.
+You can configure metrics support by adding the following to your config:
+
+```yaml
+  enabled: true
+  bindAddress: 127.0.0.1
+  port: 9002
+```
+
+Below is the generated list of Prometheus metrics for Hookshot.
+
 
 ## hookshot
 | Metric | Help | Labels |

docs/setup.md

@@ -0,0 +1,83 @@
+Getting setup
+=============
+
+This page explains how to set up Hookshot for use with a Matrix homeserver.
+
+## Requirements
+
+Hookshot is fairly light on resources, and can run in as low as 100MB or so of memory. Hookshot memory requirements
+may increase depending on the traffic and the number of rooms bridged.
+
+
+## Local installation 
+
+This bridge requires at least Node 12 (though 16 is preferred), and Rust installed.
+
+To install Node.JS, [nvm](https://github.com/nvm-sh/nvm) is a good option.
+
+To install Rust, [rustup](https://rustup.rs/) is the preferred solution to stay up to date.
+
+To clone and install, run:
+
+```bash
+git clone git@github.com:Half-Shot/matrix-hookshot.git
+cd matrix-hookshot
+yarn # or npm i
+```
+
+Starting the bridge (after configuring it), is a matter of running `yarn start`.
+
+## Installation via Docker
+
+To get started quickly, you can use the Docker image [`halfshot/matrix-hookshot`](https://hub.docker.com/r/halfshot/matrix-hookshot)
+
+```bash
+docker run \
+    --name matrix-hookshot \
+    -d \
+    -p 9993:9993 \ # Homeserver port
+    -p 9000:9000 \ # Webhook port
+    -p 9002:9002 \ # Metrics port
+    -v /etc/matrix-hookshot:/data \
+    halfshot/matrix-hookshot:latest
+```
+
+Where `/etc/matrix-hookshot` would contain the configuration files `config.yml` and `registration.yml`, along with any other files needed.
+
+
+## Configuration
+
+Copy the `config.sample.yml` to a new file `config.yml`. The sample config is also hosted
+[here](./setup/sample-configuration.md) for your convienence.
+
+You should read and fill this in as the bridge will not start without a complete config.
+
+Copy `registration.sample.yml` into `registration.yml` and fill in:
+- At a minimum, you will need to replace the `as_token` and `hs_token` and change the domain part of the namespaces.
+
+You will need to link the registration file to the homeserver. Consult your homeserver documentation
+on how to add appservices. [Synapse documents the process here](https://matrix-org.github.io/synapse/latest/application_services.html)
+
+### Webhooks configuration
+
+You will need to configure the webhooks listener at a minimum to make the bridge functional.
+To do this, ensure that your configuration for `webhook` is correct:
+
+```yaml
+webhook:
+  port: 5061
+  host: 0.0.0.0
+```
+
+You will also need to make this port accessible to the internet so services like GitHub can reach the bridge. It
+is reccomended to factor hookshot into your load balancer configuration, but currrently this process is left as an
+excercise to the user.
+
+### Services configuration
+
+You will need to configure some services. Each service has it's own documentation file inside the the setup subdirectory.
+
+- [GitHub](./setup/github.md)
+- [GitLab](./setup/gitlab.md)
+- [Jira](./setup/jira.md)
+- [Webhooks](./setup/webhooks.md)

docs/setup/github.md

@@ -1 +1,88 @@
-# GitHub
+Setting up GitHub
+======
+
+In order to bridge GitHub with Hookshot, you will need to create a GitHub App.
+
+## GitHub App
+
+This bridge requires a [GitHub App](https://github.com/settings/apps/new). You will need to create one.
+
+Most of the configuration can be left up to you, but the important points are:
+ - The callback URL should be set if you plan to use OAuth.
+ - The webhook URL should point to the public address of your hookshot instance, at the `/` path. A secret **must** be given.
+ - A client secret should be generated and stored.
+
+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
+    - Discussions (`read`)
+
+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 setup your app, you can move onto configuring the bridge:
+
+## Configuration
+
+The GitHub service requires a few connection options.
+
+```yaml
+github:
+  auth:
+    id: 123
+    privateKeyFile: github-key.pem
+  webhook:
+    secret: secrettoken
+  oauth:
+    client_id: foo
+    client_secret: bar
+    redirect_uri: https://example.com/bridge_oauth/
+  defaultOptions:
+    showIssueRoomLink: false
+```
+
+In the `auth` section, you will need to supply the **App ID** given in your GitHub App page.
+You should also supply the page to a generated private key file.
+
+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's webhooks port, 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](../usage/room_configuration/github_repo.md#configuration)
+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](../usage/auth.md), and then [bridging a room](../usage/room_configuration/github_repo.md#setting-up)

docs/setup/gitlab.md

@@ -1 +1,50 @@
 # GitLab
+
+Setting up GitLab requires that you have access to create webhooks on repositories.
+
+## Configuration
+
+GitLab configuration is fairly straight-forward:
+
+```yaml
+  # (Optional) Configure this to enable GitLab support
+  #
+  instances:
+    gitlab:
+      url: https://gitlab.com
+  webhook:
+    secret: secrettoken
+```
+
+You neeed to list all the instances you plan to connect to in the `config.yml`. This is
+used so that users can give a short name like `gitlab` or `matrix.org` when they want
+to specify an instance.
+
+The webhooks secret should be generated, for use in your repositories.
+
+## Adding a repository
+
+Adding a repository is a case of navigating to the settings page, and then adding a new webhook.
+You will want to give the URL of the public address for the hookshot webhooks port on the `/` path.
+
+You should add the events you wish to trigger on. Hookshot currently supports:
+
+- Push events
+- Tag events
+- Issues events
+- Merge request events
+- Releases events
+
+You will need to do this each time you want to a repository to hookshot. 
+
+To then bridge a room to GitLab, you will need to add a `uk.half-shot.matrix-hookshot.gitlab.repository`
+ *state event* to a room containing a content of:
+
+```json5
+{
+    "instance": "gitlab", // your instance name
+    "path": "yourusername/repo" // the full path to the repo
+}
+```
+
+Once this is done, you are bridged 🥳.

docs/setup/jira.md

@@ -1 +1,3 @@
 # JIRA
+
+TODO

docs/setup/sample-configuration.md

@@ -0,0 +1,9 @@
+# Sample Configuration
+
+Below is a sample bridge configuration file. The configuration file 
+can be tweaked to change the behaviour of your bridge. A bridge of the server is 
+required to apply any changes made to this file.
+
+```yaml
+{{#include ../../config.sample.yml}}
+```

docs/setup/webhooks.md

@@ -1 +1,85 @@
 # Webhooks
+
+Hookshot supports generic webhook support so that services can send messages into Matrix rooms without being aware of the Matrix protocol.
+
+## Features
+
+The webhook connection supports sending messages into a single Matrix room, by hitting an API endpoint.
+
+## Configuration
+
+You will need to add the following configuration to the config file.
+
+```yaml
+generic:
+  enabled: true
+  urlPrefix: https://example.com/mywebhookspath/
+  allowJsTransformationFunctions: false
+```
+
+The bridge listens for incoming webhooks on the host and port provided in the `webhook` configuration section. For example,
+a internal hook URL (using the default port) would look like `http://0.0.0.0:9000/abcdef`.
+
+`urlPrefix` describes the public facing URL of your webhook handler. For instance, if your load balancer redirected
+webhook requests from `https://example.com/mywebhookspath` to the bridge, an example webhook URL would look like:
+`https://example.com/mywebhookspath/abcdef`.
+
+## Adding a webhook
+
+To add a webhook to your room:
+  - Invite the bot user to the room.
+  - Make sure the bot able to send state events (usually the Moderator power level in clients)
+  - Say `!setup webhook`
+  - The bot will respond with the webhook URL to be sent to services.
+
+## Endpoint options
+
+The webhook endpoint can handle a `GET`,`POST` or `PUT` request.
+
+If the request is a `GET` request, the query parameters are assumed to be the body.
+otherwise, the body of the request should be a JSON payload.
+
+If the body contains a `text` key, then that key will be used as a message body in Matrix.
+If the body *also* contains a `username` key, then the message will be prepended by the given username.
+
+Otherwise, the full JSON payload will be sent to the room. This can be adapted into a message by creating a **JavaScript transformation function**.
+
+## JavaScript Transformations
+
+<section class="notice">
+Although every effort has been made to securely sandbox scripts, running untrusted code from users is always risky. Ensure safe permissions
+in your room to prevent users from tampering with the script.
+</section>
+
+This bridge support creating small JavaScript snippets to translate an incoming webhook payload into a message for the room, giving
+you a very powerful ability to generate messages based on whatever input is coming in.
+
+The input is parsed and exectuted within a seperate JavaScript Virtual Machine context, and is limited to an execution time of 2 seconds.
+With that said, the feature is disabled by default and `allowJsTransformationFunctions` must be enabled in the config.
+
+The code snippets can be edited by editing the Matrix state event corresponding to this connection (with a state type of `uk.half-shot.matrix-hookshot.generic.hook`).
+Because this is a fairly advanced feature, this documentation won't go into how to edit state events from your client.
+Please seek out documentation from your client on how to achieve this. 
+
+The script string should be set within the state event under the `transformationFunction` key.
+
+### Script API
+
+The scripts have a very minimal API. The execution environment will contain a `data` field, which will be the body
+of the incoming request (JSON will be parsed into an `Object`). Scripts are executed syncronously and a variable `result`
+is expected to be set in the execution, which will be used as the text value for the script. `result` will be automatically
+transformed by a Markdown parser.
+
+If the script contains errors or is otherwise unable to work, the bridge will send an error to the room.
+
+### Example script
+
+Where `data` = `{"counter": 5, "maxValue": 4}`
+
+```js
+if (data.counter > data.maxValue) {
+    result = `**Oh no!** The counter has gone over by ${data.counter - data.maxValue}`
+} else {
+    result = `*Everything is fine*, the counter is under by ${data.maxValue - data.counter}`
+}
+```

docs/usage.md

@@ -0,0 +1,18 @@
+Usage
+=====
+
+This section covers how to use the bridge, once it's set up. We break these
+down into categories:
+
+- Authentication: How to connect your user account to a remote service to use
+  rich commands.
+- Room Connections: How to start connecting rooms to services.
+
+If you are looking for help on what bot commands you can run in a room, you can
+refer to the help information by saying\*:
+
+- `!gh help` in rooms connected to GitHub.
+- `!gl help` in rooms connected to GitLab.
+- `!jira help` in rooms connected to JIRA.
+
+\*the prefix may vary if the `commandPrefix` configuration in the room is set.

docs/usage/auth.md

@@ -0,0 +1,58 @@
+# Authenticating
+
+To authenticate with services, you must first have a DM room with the bridge set up. In this guide,
+we are going to assume the bot is called `@hookshot:example.com` but this will vary for your setup. For all
+the instructions below, commands should only be executed in the DM room.
+
+## GitHub
+
+You can authenticate via OAuth or a Personal Access Token (PAT) when using GitHub. Authentication is required
+when trying to bridge GitHub resources into rooms.
+
+<section class="notice">
+Please note that you will need a Personal Access Token in order to bridge your personal GitHub notifications.
+This is a limitation of GitHub's API.
+</section>
+
+
+To authenticate with a personal access token:
+1. Open [https://github.com/settings/tokens](https://github.com/settings/tokens) (Github > Settings > Developer Settings / Personal access tokens)
+1. Click **Generate new token**
+1. Give it a good name, and a sensible expiration date. For scopes you will need:
+    - Repo (to access repo information)
+      - public_repo
+      - repo:status
+    - Workflow (if you want to be able to launch workflows / GitHub actions from Matrix)
+    - Notifications (if you want to bridge in your notifications to Matrix)
+    - User
+      - read:user
+    - write:discussion (for GitHub discussion support)
+      - read:discussion
+
+1. Send the generated token to the bridge by saying `github setpersonaltoken %your-token%`. You can redact
+  the message afterwards if you like.
+1. The bridge will have connected you. You can check the status at any time by saying `github hastoken`
+
+## GitLab
+
+You can authenticate with GitLab by supplying a Personal Access Token. OAuth-style authentication isn't supported
+yet.
+
+- You will need to have configured a GitLab instance in your config.yml for the instance you want to login to.
+- Open https://%instance%/-/profile/personal_access_tokens (GitLab > User Settings > Access Tokens), where instance is your GitLab instance address.
+  - For the public GitLab server, this would be "gitlab.com"
+- Give it a good name, and a sensible expiration date. For scopes you will need to tick `api`.
+- Send the generated token to the bridge by saying `gitlab personaltoken %instance% %your-token%`. You can redact
+  the message afterwards if you like.
+- The bridge will have connected you. You can check the status at any time by saying `gitlab hastoken %instance% `
+
+
+## JIRA
+
+You can login to JIRA via OAuth. This means you will need to have configured OAuth support in your `config.yml`, and
+have the endpoints required accessible from the internet. Authentication is required when trying to bridge JIRA resources into rooms.
+
+- Say `jira login` to get the URL to authenticate via.
+- Click the URL sent by the bot.
+- Follow the steps, ensuring you authenticate with the right user.
+- If all goes well, you will now be connected. You can check the status and authorisatied instances by saying `jira whoami`

docs/usage/dynamic_rooms.md

@@ -0,0 +1,26 @@
+Dynamic Rooms
+=============
+
+<section class="notice">
+Anyone who has access to your homeserver can query these aliases (even over federation), and aliases
+ do not support checking if a user is authorised to view the content before creation. If you are bridging non-public
+ content, it is advisable to disable this feature.
+</section>
+
+
+Some bridges support dynamically creating rooms that point to resources based on an alias given by a user.
+
+Presently, the following are supported:
+
+- `#github_$owner:example.com` - For a Matrix space containing a user's discussions and repositories
+- `#github_$owner_$repo:example.com` - For GitHub repositories
+- `#github_$owner_$repo_$issuenumber:example.com` - For GitHub issues
+- `#github_disc_$owner_$repo:example.com` - For GitHub discussions for a repository
+
+Where $word is replaced by the appropriate value.
+
+(Some of these may not be supported, depending on bridge configuration and registration file changes)
+
+## Disabling support
+
+This feature can be disabled simply by removing alias fields from the registration file.

docs/usage/room_configuration.md

@@ -0,0 +1,26 @@
+Room Configuration
+==================
+
+Hookshot works off the principle of **Connections**.
+
+
+A room can have many connections to different services. The connections are defined
+in the room state of a room. A connection defines the service it connects to, the 
+type of integration (e.g. GitHub repo, Jira Project) and any additional configuration.
+
+<figure>
+{{#include ./room_configuration/connections1.svg}}
+<figcaption>Figure 1. An example of a room connected to GitHub and JIRA</figcaption>
+</figure>
+
+Hookshot supports several connection types, which are defined under the Room Configuration
+heading.
+
+The availablilty of connection types depends on the configuration provided to hookshot.
+
+
+### The `!hookshot` command
+
+Rooms can be bridged by inviting the hookshot bot into a room, and then running the 
+`!hookshot` command. Running `!hookshot help` will give you some details, but you should
+see the documentation provided for information on each connection type.

docs/usage/room_configuration/github_repo.md

@@ -0,0 +1,52 @@
+GitHub Repository
+=================
+
+This connection type connects a GitHub repository (e.g. https://github.com/Half-Shot/matrix-hookshot) to a room.
+
+You can run commands to create and manipulate issues, and recieve notifications when something changes such as
+a new release.
+
+## Setting up
+
+To set up a connection to a GitHub Repository in a new room:
+
+(N.B you must have permission to bridge GitHub repositories before you can use this command, see [auth](../auth.html#github))
+
+1. Invite the bridge bot (e..g `@hookshot:example.com`)
+2. Give the bridge bot moderator permissions or higher (power level 50).
+3. Send the command `!hookshot github repo https://github.com/my/project`
+4. If you have permission to bridge this repo, the bridge will respond with a confirmation message.
+5. Note: The bridge will need to either:
+    - Have a GitHub installation registered with the organisation
+    - The requesting user must be authenticated with the bridge via OAuth and the repository must be part of their GitHub account.
+
+## Configuration
+
+This connection supports a few options which can be defined in the room state:
+
+| Option | Description | Allowed values | Default |
+|--------|-------------|----------------|---------| 
+|ignoreHooks|Choose to exclude notifications for some event types|Array of: [Supported event types](#supported-event-types) |*empty*|
+|commandPrefix|Choose the prefix to use when sending commands to the bot|A string, ideally starts with "!"|`!gh`|
+|showIssueRoomLink|When new issues are created, provide a Matrix alias link to the issue room|`true/false`|`false`|
+|prDiff|Show a diff in the room when a PR is created, subject to limits|`{enabled: boolean, maxLines: number}`|`{enabled: false}`|
+|includingLabels|Only notify on issues matching these label names|Any string matching a label name|*empty*|
+|excludingLabels|Never notify on issues matching these label names|Any string matching a label name|*empty*|
+
+
+### Supported event types
+
+This connection supports sending messages when the following actions happen on the repository.
+
+- issue
+  - issue.created
+  - issue.changed
+  - issue.edited
+- pull_request
+  - pull_request.closed
+  - pull_request.merged
+  - pull_request.opened
+  - pull_request.ready_for_review
+  - pull_request.reviewed
+- release
+  - release.created

registration.sample.yml

@@ -7,9 +7,9 @@ namespaces:
     - regex: "@_github_.*:foobar" # Where foobar is your homeserver's domain
       exclusive: true
   aliases:
-    - regex: "#github_.+_.+_\\d+:foobar"  # Where foobar is your homeserver's domain
+    - regex: "#github_.+:foobar"  # Where foobar is your homeserver's domain
       exclusive: true
 
-sender_localpart: github
+sender_localpart: hookshot
 url: "http://localhost:9993" # This should match the bridge.port in your config file
-rate_limited: false
+rate_limited: false

scripts/build-metrics-docs.ts

@@ -26,7 +26,16 @@ Object.entries(anyRegister._metrics).map(
 console.log(`Prometheus Metrics
 ==================
 
-Below is the generated list of prometheus metrics for hookshot.
+You can configure metrics support by adding the following to your config:
+
+\`\`\`yaml
+  enabled: true
+  bindAddress: 127.0.0.1
+  port: 9002
+\`\`\`
+
+Below is the generated list of Prometheus metrics for Hookshot.
+
 `)
 
 Object.entries(categories).forEach(([name, entries]) => {

src/Config/Config.ts

@@ -3,6 +3,7 @@ import { promises as fs } from "fs";
 import { IAppserviceRegistration } from "matrix-bot-sdk";
 import * as assert from "assert";
 import { configKey } from "./Decorators";
+import { GitHubRepoConnectionOptions } from "../Connections/GithubRepo";
 
 interface BridgeConfigGitHubYAML {
     auth: {
@@ -20,9 +21,7 @@ interface BridgeConfigGitHubYAML {
         // eslint-disable-next-line camelcase
         redirect_uri: string;
     };
-    defaultOptions?: {
-        showIssueRoomLink: false;
-    }
+    defaultOptions?: GitHubRepoConnectionOptions;
 }
 
 export class BridgeConfigGitHub {
@@ -45,9 +44,7 @@ export class BridgeConfigGitHub {
         redirect_uri: string;
     };
     @configKey("Default options for GitHub connections.", true)
-    defaultOptions?: {
-        showIssueRoomLink: false;
-    };
+    defaultOptions?: GitHubRepoConnectionOptions;
 
     constructor(yaml: BridgeConfigGitHubYAML) {
         this.auth = yaml.auth;

src/Connections/GithubRepo.ts

@@ -31,9 +31,7 @@ interface IQueryRoomOpts {
     githubInstance: GithubInstance;
 }
 
-export interface GitHubRepoConnectionState {
-    org: string;
-    repo: string;
+export interface GitHubRepoConnectionOptions {
     ignoreHooks?: AllowedEventsNames[],
     commandPrefix?: string;
     showIssueRoomLink?: boolean;
@@ -44,6 +42,11 @@ export interface GitHubRepoConnectionState {
     includingLabels?: string[];
     excludingLabels?: string[];
 }
+export interface GitHubRepoConnectionState extends GitHubRepoConnectionOptions{
+    org: string;
+    repo: string;
+}
+
 
 const GITHUB_REACTION_CONTENT: {[emoji: string]: string} = {
     "👍": "+1",

src/Connections/SetupConnection.ts

@@ -64,7 +64,6 @@ export class SetupConnection extends CommandConnection {
         const [, org, repo] = res;
         let resultRepo
         try {
-            log.info("DATA:", org, repo);
             resultRepo = await octokit.repos.get({owner: org, repo});
         } catch (ex) {
             throw new CommandError("Invalid GitHub repo", "Could not find the requested GitHub repo. Do you have permission to view it?");
@@ -148,4 +147,4 @@ export class SetupConnection extends CommandConnection {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const res = compileBotCommands(SetupConnection.prototype as any, CommandConnection.prototype as any);
 SetupConnection.helpMessage = res.helpMessage;
-SetupConnection.botCommands = res.botCommands;
+SetupConnection.botCommands = res.botCommands;