1.0.0

CHANGELOG.md

@@ -0,0 +1,51 @@
+1.0.0 (2021-12-21)
+===================
+
+This release is huge, containing not only a rename but many new features and bug fixes. To name some of the highlights:
+
+- The bridge has now been renamed from `matrix-github` to `matrix-hookshot`.
+- Now supports JIRA and Generic Webhooks in addition to GitHub and GitLab.
+- Includes new commands and metrics reporting.
+- Includes complete documentation.
+
+As always, please contact me (@Half-Shot:half-shot.uk) if you require any help getting this setup and please report any bugs you encounter!
+
+Features
+--------
+
+- The bridge now supports generic webhook bridging. ([\#77](https://github.com/half-shot/matrix-hookshot/issues/77))
+- Add support for JIRA. ([\#82](https://github.com/half-shot/matrix-hookshot/issues/82))
+- Add Provisioning API. Extra thanks to @turt2live for supporting this change. ([\#83](https://github.com/half-shot/matrix-hookshot/issues/83))
+- GitHub support no longer needs an installation ID defined.
+  Licence in package.json now accurately reflects `LICENCE`
+  GitHub workflows can now be run with `!gh workflow run` on GitHubRepo connections. ([\#85](https://github.com/half-shot/matrix-hookshot/issues/85))
+- Add `!hookshot` setup command for quickly setting up new rooms with the bridge. ([\#88](https://github.com/half-shot/matrix-hookshot/issues/88))
+- Issues created with !gh create show the issue number inside a reaction.
+  GitHubRepo connections can now optionally show a small diff for PRs.
+  PRs can be reviewed by replying with a ✅ or a ❌ and a small text message. ([\#93](https://github.com/half-shot/matrix-hookshot/issues/93))
+- Add support for `includingLabels`/`excludingLabels` state config for GitHubRepo and GitLab Repo connections, allowing rooms to recieve a subset of issue and PR/MR notifications based on labels. ([\#95](https://github.com/half-shot/matrix-hookshot/issues/95))
+- Add automatic changelog generation via [Towncrier](https://github.com/twisted/towncrier). ([\#96](https://github.com/half-shot/matrix-hookshot/issues/96))
+- Add support for exporting [Prometheus](https://prometheus.io) metrics. ([\#99](https://github.com/half-shot/matrix-hookshot/issues/99))
+- Switch to using the `vm2` module for improved sandboxing of transformation functions ([\#101](https://github.com/half-shot/matrix-hookshot/issues/101))
+- Allow running multiple resources on the same HTTP listener. See the new `listeners` config.([\#102](https://github.com/half-shot/matrix-hookshot/issues/102))
+
+
+
+Improved Documentation
+----------------------
+
+- Add documentation for most functionality in the bridge. ([\#90](https://github.com/half-shot/matrix-hookshot/issues/90))
+
+
+Internal Changes
+----------------
+
+- The bridge now depends on Rust modules for some functionality. ([\#78](https://github.com/half-shot/matrix-hookshot/issues/78))
+- The project has been renamed `matrix-hookshot`. ([\#81](https://github.com/half-shot/matrix-hookshot/issues/81))
+- Use quotes instead of brackets in GH PRs. Thanks @Twi1ightSparkle! ([\#92](https://github.com/half-shot/matrix-hookshot/issues/92))
+- Fix spelling of received. Thanks @andybalaam! ([\#94](https://github.com/half-shot/matrix-hookshot/issues/94))
+- CI jobs now report the diff between the generated config and the in-tree sample config. ([\#97](https://github.com/half-shot/matrix-hookshot/issues/97))
+
+0.1.0 (2021-04-21)
+==================
+This is the initial release of the GitHub bridge.

changelog.d/101.feature

@@ -1 +0,0 @@
-Switch to using the `vm2` module for improved sandboxing of transformation functions

changelog.d/102.feature

@@ -1 +0,0 @@
-Allow running multiple resources on the same HTTP listener. See the new `listeners` config.

changelog.d/77.feature

@@ -1 +0,0 @@
-The bridge now supports generic webhook bridging.

changelog.d/78.misc

@@ -1 +0,0 @@
-The bridge now depends on Rust modules for some functionality.

changelog.d/81.misc

@@ -1 +0,0 @@
-The project has been renamed `matrix-hookshot`.

changelog.d/82.feature

@@ -1 +0,0 @@
-Add support for JIRA.

changelog.d/83.feature

@@ -1 +0,0 @@
-Add Provisioning API. Extra thanks to @turt2live for supporting this change.

changelog.d/85.feature

@@ -1,3 +0,0 @@
-GitHub support no longer needs an installation ID defined.
-Licence in package.json now accurately reflects `LICENCE`
-GitHub workflows can now be run with `!gh workflow run` on GitHubRepo connections.

changelog.d/88.feature

@@ -1 +0,0 @@
-Add `!hookshot` setup command for quickly setting up new rooms with the bridge.

changelog.d/90.doc

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

changelog.d/92.misc

@@ -1 +0,0 @@
-Use quotes instead of brackets in GH PRs. Thanks @Twi1ightSparkle!

changelog.d/93.feature

@@ -1,3 +0,0 @@
-Issues created with !gh create show the issue number inside a reaction.
-GitHubRepo connections can now optionally show a small diff for PRs.
-PRs can be reviewed by replying with a ✅ or a ❌ and a small text message.

changelog.d/94.misc

@@ -1 +0,0 @@
-Fix spelling of received. Thanks @andybalaam!

changelog.d/95.feature

@@ -1 +0,0 @@
-Add support for `includingLabels`/`excludingLabels` state config for GitHubRepo and GitLab Repo connections, allowing rooms to recieve a subset of issue and PR/MR notifications based on labels.

changelog.d/96.feature

@@ -1 +0,0 @@
-Add automatic changelog generation via [Towncrier](https://github.com/twisted/towncrier).

changelog.d/97.misc

@@ -1 +0,0 @@
-CI jobs now report the diff between the generated config and the in-tree sample config.

changelog.d/99.feature

@@ -1 +0,0 @@
-Add support for exporting [Prometheus](https://prometheus.io) metrics.

docs/auth.md

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

docs/setup/github.md

@@ -1,8 +1,5 @@
 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.

docs/setup/gitlab.md

@@ -1,7 +1,5 @@
 # GitLab
 
-Setting up GitLab requires that you have access to create webhooks on repositories.
-
 ## Configuration
 
 GitLab configuration is fairly straight-forward:

docs/setup/jira.md

@@ -1,3 +1,58 @@
 # JIRA
 
-TODO
+## Adding a webhook to a JIRA Organisation
+
+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.
+
+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 bridge.
+
+
+## JIRA OAuth
+
+<section class="notice">
+The JIRA service currently only supports atlassian.com (JIRA SaaS) when handling user authentication.
+Support for on-prem deployments is hoping to land soon.
+</section>
+
+
+You will need a Atlassain 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
+
+## Configuration
+
+You can now set some configuration in the bridge `config.yml`
+
+```yaml
+jira:
+  webhook:
+    secret: auto-generated-config
+  oauth:
+    client_id: s2tkGiqj5TS1SOBlDP9Mc3e8m15w07pL
+    client_secret: wQcADRX_rw_6VmuFBOYPi6H9Q_Lh2fNsqTu520cX5IdqoUETH1zStFItmkDtEJtA
+    redirect_uri: https://f6bd-82-129-52-204.ngrok.io/jira/oauth
+```
+
+You can leave the `oauth` section blank if you are not planning to use those capabilities.
+
+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's webhooks port, you should use the path `https://example.com/hookshot/oauth`.
+This value MUST exactly match the **Callback URL** on the JIRA integration page page.
+
+## 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).

package.json

@@ -1,7 +1,7 @@
 {
   "name": "matrix-hookshot",
-  "version": "0.1.0",
-  "description": "A bridge that displays GitHub issues/PRs as rooms.",
+  "version": "1.0.0",
+  "description": "A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA.",
   "main": "lib/app.js",
   "repository": "https://github.com/Half-Shot/matrix-hookshot",
   "author": "Half-Shot",