Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +diff --git a/1.0.0/.nojekyll b/1.0.0/.nojekyll new file mode 100644 index 00000000..f1731109 --- /dev/null +++ b/1.0.0/.nojekyll @@ -0,0 +1 @@ +This file makes sure that Github Pages doesn't process mdBook's output. diff --git a/1.0.0/404.html b/1.0.0/404.html new file mode 100644 index 00000000..b549e83b --- /dev/null +++ b/1.0.0/404.html @@ -0,0 +1,190 @@ + + +
+ + +This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +This section is not complete yet for end users. For developers, you can read the documentation for the API below:
+This document describes how to integrate with matrix-hookshot
's provisoning API.
Requests made to the bridge must be against the API listener defined in the config under provisioning
, not
+the appservice or webhook listeners.
Requests should always be authenticated with the secret given in the config, inside the Authorization
header.
+Requests being made on behalf of users (most provisioning APIs) should include the userId as a query parameter.
GET /v1/health?userId=%40Half-Shot%3Ahalf-shot.uk
+Authorization: Bearer secret
+
+APIs are versioned independently so two endpoints on the latest version may not always have the same version.
+Request the status of the provisoning API.
+HTTP 200
+{}
+
+Any other response should be considered a failed request (e.g. 404, 502 etc).
+Request the connection types enabled for this bridge.
+{
+ "JiraProject": {
+ "type": "JiraProject", // The name of the connection
+ "eventType": "uk.half-shot.matrix-hookshot.jira.project", // Corresponds to the state type for the connection
+ "service": "jira", // or github, webhook. A human-readable service name to make things look pretty
+ "botUserId": "@hookshot:yourdomain.com", // The bot mxid for the service. Currently this is the sender_localpart, but may change in the future.
+ }
+}
+
+Request the connections for a given room. The {roomId}
parameter is the target Matrix room.
[{
+ "type": "JiraProject", // The name of the connection
+ "eventType": "uk.half-shot.matrix-hookshot.jira.project", // Corresponds to the state type in the connection
+ "id": "opaque-unique-id", // An opaque ID used to refer to this connection. Should **NOT** be assumed to be stable.
+ "service": "jira", // or github, webhook. A human-readable service name to make things look pretty
+ "botUserId": "@hookshot:yourdomain.com", // The bot mxid for the service. Currently this is the sender_localpart, but may change in the future.
+ "config": {
+ // ... connection specific details, can be configured.
+ }
+}]
+
+Request details of a single connection. The {roomId}
parameter is the target Matrix room.
{
+ "type": "JiraProject", // The name of the connection
+ "eventType": "uk.half-shot.matrix-hookshot.jira.project", // Corresponds to the state type in the connection
+ "id": "opaque-unique-id", // An opaque ID used to refer to this connection. Should **NOT** be assumed to be stable.
+ "service": "jira", // or github, webhook. A human-readable service name to make things look pretty
+ "botUserId": "@hookshot:yourdomain.com", // The bot mxid for the service. Currently this is the sender_localpart, but may change in the future.
+ "config": {
+ // ... connection specific details, can be configured.
+ }
+}
+
+Create a new connection of a given type. The type refers to the eventType
(IConnection.CanonicalEventType
). The {roomId}
parameter is the target Matrix room.
The body of the request is the configuration for the connection, which will be the "ConnectionState" interface for each connection.
+{
+ // ... connection specific details, can be configured.
+}
+
+{
+ "type": "JiraProject", // The name of the connection
+ "eventType": "uk.half-shot.matrix-hookshot.jira.project", // Corresponds to the state type in the connection
+ "id": "opaque-unique-id", // An opaque ID used to refer to this connection. Should **NOT** be assumed to be stable.
+ "service": "jira", // or github, webhook. A human-readable service name to make things look pretty
+ "botUserId": "@hookshot:yourdomain.com", // The bot mxid for the service. Currently this is the sender_localpart, but may change in the future.
+ "config": {
+ // ... connection specific details, can be configured.
+ }
+}
+
+Update a connection's configuration. The id
refers to the id
returned in the GET response.
The body of the request is the configuration for the connection, which will be the "ConnectionState" interface for each connection.
+{
+ // ... connection specific details, can be configured.
+}
+
+{
+
+ "type": "JiraProject", // The name of the connection
+ "eventType": "uk.half-shot.matrix-hookshot.jira.project", // Corresponds to the state type in the connection
+ "id": "opaque-unique-id", // An opaque ID used to refer to this connection. Should **NOT** be assumed to be stable.
+ "service": "jira", // or github, webhook. A human-readable service name to make things look pretty
+ "botUserId": "@hookshot:yourdomain.com", // The bot mxid for the service. Currently this is the sender_localpart, but may change in the future.
+ "config": {
+ // ... connection specific details, can be configured.
+ }
+}
+
+Delete a connection. The id
refers to the id
returned in the GET response.
{
+ "ok": true
+}
+
+Some services have specific APIs for additional functionality, like OAuth.
+Request an OAuth url for the given user. Once the user has completed the steps in the OAuth process, +the bridge will be granted access.
+[{
+ "user_url": "https://github.com/login/oauth/authorize?...",
+ "org_url": "https://github.com/apps/matrix-bridge/installations/new",
+}]
+
+Request the status of the users account. This will return a loggedIn
value to determine if the
+bridge has a GitHub identity stored for the user, and any organisations they have access to.
{
+ "loggedIn": true,
+ "organisations":[{
+ "name": "half-shot",
+ "avatarUrl": "https://avatars.githubusercontent.com/u/8418310?v=4"
+ }]
+}
+
+Request a list of all repositories a user is a member of in the given org. The owner
and name
value of a repository can be given to create a new GitHub connection.
This request is paginated, and page
sets the page (defaults to 1
) while perPage
(defaults to 10
) sets the number of entries per page.
This request can be retried until the number of entries is less than the value of perPage
.
{
+ "loggedIn": true,
+ "repositories":[{
+ "name": "matrix-hookshot",
+ "owner": "half-shot",
+ "fullName": "half-shot/matrix-hookshot",
+ "avatarUrl": "https://avatars.githubusercontent.com/u/8418310?v=4",
+ "description": "A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA. "
+ }]
+}
+
+Request a list of all repositories a user is a member of (including those not belonging to an org). The owner
and name
value of a repository can be given to create a new GitHub connection.
If the user has only allowed a subset of repositories to be bridged, changeSelectionUrl
will be defined and can be used to expand the search query.
This request is paginated, and page
sets the page (defaults to 1
) while perPage
(defaults to 10
) sets the number of entries per page.
This request can be retried until the number of entries is less than the value of perPage
.
{
+ "loggedIn": true,
+ "changeSelectionUrl": "https://github.com/settings/installations/12345",
+ "repositories":[{
+ "name": "matrix-hookshot",
+ "owner": "half-shot",
+ "fullName": "half-shot/matrix-hookshot",
+ "avatarUrl": "https://avatars.githubusercontent.com/u/8418310?v=4",
+ "description": "A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA. "
+ }]
+}
+
+Request an OAuth url for the given user. Once the user has completed the steps in the OAuth process, +the bridge will be granted access.
+{
+ "url": "https://auth.atlassian.com/authorize?..."
+}
+
+Request the status of the users account. This will return a loggedIn
value to determine if the
+bridge has a JIRA identity stored for the user, and any instances they have access to. Note that if a
+user does not have access to an instance, they can authenticate again to gain access to it (if they are able
+to consent).
{
+ "loggedIn": true,
+ "instances":[{
+ "name": "acme",
+ "url": "https://acme.atlassian.net"
+ }]
+}
+
+Request a list of all projects a user can see in a given instance. The url
value of a project can be given to create
+a new JIRA connection.
[{
+ "key": "PLAY",
+ "name": "Jira Playground",
+ "url": "https://acme.atlassian.net/projects/PLAY"
+}]
+
+
+ Hookshot supports running in a worker configuration, using Redis as the middleman process to handle traffic between processes.
+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:
+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.
+ +Previously matrix-github
+ +A bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA.
+This bridge bridges:
+Documentation can be found on GitHub Pages.
+You can build the documentaion yourself by:
+# cargo install mdbook
+mdbook build
+sensible-browser book/index.html
+
+TODO...
+ +