Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +diff --git a/1.7.2/.nojekyll b/1.7.2/.nojekyll new file mode 100644 index 00000000..f1731109 --- /dev/null +++ b/1.7.2/.nojekyll @@ -0,0 +1 @@ +This file makes sure that Github Pages doesn't process mdBook's output. diff --git a/1.7.2/404.html b/1.7.2/404.html new file mode 100644 index 00000000..f9db1d57 --- /dev/null +++ b/1.7.2/404.html @@ -0,0 +1,193 @@ + + +
+ + +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": "matrix-org",
+ "fullName": "matrix-org/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": "matrix-org",
+ "fullName": "matrix-org/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 using widgets to configure connections in rooms. Widgets allow users to view and configure rooms without the need to type commands. The widget feature is designed to complement +the existing command system, rather than replace it.
+widgets:
+ addToAdminRooms: false
+ roomSetupWidget:
+ addOnInvite: false
+# disallowedIpRanges:
+# - 127.0.0.0/8
+# - 10.0.0.0/8
+# - 172.16.0.0/12
+# - 192.168.0.0/16
+# - 100.64.0.0/10
+# - 192.0.0.0/24
+# - 169.254.0.0/16
+# - 192.88.99.0/24
+# - 198.18.0.0/15
+# - 192.0.2.0/24
+# - 198.51.100.0/24
+# - 203.0.113.0/24
+# - 224.0.0.0/4
+# - ::1/128
+# - fe80::/10
+# - fc00::/7
+# - 2001:db8::/32
+# - ff00::/8
+# - fec0::/10
+ publicUrl: http://example.com/widgetapi/v1/static
+ branding:
+ widgetTitle: Hookshot Configuration
+ openIdOverrides:
+ my-local-server: "http://localhost"
+
+The admin room feature is still very barebones so while it's included here for completeness, most instances
+should leave addToAdminRooms
off (as it is by default). This flag will add an "admin room" widget to user admin rooms.
The room setup feature is more complete, supporting generic webhook configuration (with more options coming soon).
+This can be enabled by setting roomSetupWidget
to an object. You can add the widget by saying !hookshot setup-widget
in any room.
+When addOnInvite
is true, the bridge will add a widget to rooms when the bot is invited, and the room has no existing connections.
disallowedIpRanges
describes which IP ranges should be disallowed when resolving homeserver IP addresses (for security reasons).
+Unless you know what you are doing, it is recommended to not include this key. The default blocked IPs are listed above for your convienence.
publicUrl
should be set to the publically reachable address for the widget public
content. By default, hookshot hosts this content on the
+widgets
listener under /widgetapi/v1/static
.
branding
allows you to change the strings used for various bits of widget UI. At the moment you can:
widgetTitle
to change the title of the widget that is created.openIdOverrides
allows you to configure the correct federation endpoints for a given set of Matrix server names. This is useful if you are
+testing/developing hookshot in a local dev environment. Production environments should not use this configuration (as their Matrix server name
+should be resolvable). The config takes a mapping of Matrix server name => base path for federation.
+E.g. if your server name was my-local-server
and you federation was readable via http://localhost/_matrix/federation,
+you would put configure my-local-server: "http://localhost
.
In addition to setting up the widgets config, you must bind a listener for the widgets resource in your listeners
config.
listeners:
+ - port: 5069
+ bindAddress: 0.0.0.0
+ resources:
+ - widgets
+
+See the setup page for more information on listeners.
+The API for widgets is currently in flux due to being fairly new, and it's not reccomended +to develop against it at this time. At a future date this API will be merged with the existing +provisioning API and the details will be published.
+ +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: false
+ 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.
+ +A good issue can mean the difference between a quick fix and a long, painful fixing process. That's why the +following guidelines exist:
+Cannot create a nick with | in it
is a good issue title. Filter nicks according to RFC 2812
+is not a good issue title.matrix-appservice-bridge
being used.This project follows "git flow" semantics. In practice, this means:
+master
branch is latest current stable release.develop
branch is where all the new code ends up.develop
and then write your code.yarn test && yarn lint
.changelog.d
. A changelog filename should be ${GithubPRNumber}.{bugfix|misc|feature|doc|removal}
+The change should include information that is useful to the user rather than the developer.
+You can choose to sign your changelog entry to be credited by appending something like "Thanks to @Half-Shot"
+at the end of the file, on the same line.Hi there! Please read the CONTRIBUTING.md guide for all matrix.org bridge +projects.
+main
branch as the default branch (instead of develop
).GitHub
, GitLab
+which help us determine which services are affected by an issue.