Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +diff --git a/5.2.1/.nojekyll b/5.2.1/.nojekyll new file mode 100644 index 00000000..f1731109 --- /dev/null +++ b/5.2.1/.nojekyll @@ -0,0 +1 @@ +This file makes sure that Github Pages doesn't process mdBook's output. diff --git a/5.2.1/404.html b/5.2.1/404.html new file mode 100644 index 00000000..1bda0e59 --- /dev/null +++ b/5.2.1/404.html @@ -0,0 +1,193 @@ + + +
+ + +This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +Hookshot supports end-to-bridge encryption via MSC3202. As such, encryption requires Hookshot to be connected to a homeserver that supports that MSC, such as Synapse.
+In order for Hookshot to use encryption, it must be configured as follows:
+experimentalEncryption.storagePath
setting must point to a directory that Hookshot has permissions to write files into. If running with Docker, this path should be within a volume (for persistency). Hookshot uses this directory for its crypto store (i.e. long-lived state relating to its encryption keys).
+yarn start:resetcrypto
.queue.monolithic
must be set to true
.If you ever reset your homeserver's state, ensure you also reset Hookshot's encryption state. This includes clearing the experimentalEncryption.storagePath
directory and all worker state stored in your redis instance. Otherwise, Hookshot may fail on start up with registration errors.
Also ensure that Hookshot's appservice registration file contains every line from registration.sample.yml
that appears after the If enabling encryption
comment. Note that changing the registration file may require restarting the homeserver that Hookshot is connected to.
Synapse has functional support for MSC3202 as of v1.63.0. To enable it, add the following section to Synapse's configuration file (typically named homeserver.yaml
):
experimental_features:
+ msc3202_device_masquerading: true
+ msc3202_transaction_extensions: true
+ msc2409_to_device_messages_enabled: true
+
+
+ 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 provisioning 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 provisioning 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 additional bot users called "service bots" which handle a particular connection type +(in addition to the default bot user which can handle any connection type). +These bots can coexist in a room, each handling a different service.
+Service bots can be given a different localpart, display name, avatar, and command prefix.
+They will only handle connections for the specified service, which can be one of:
For example with this configuration:
+serviceBots:
+ - localpart: feeds
+ displayname: Feeds
+ avatar: "./assets/feeds_avatar.png"
+ prefix: "!feeds"
+ service: feeds
+
+There will be a bot user @feeds:example.com
which responds to commands prefixed with !feeds
, and only handles feeds connections.
For the homeserver to allow hookshot control over users, they need to be added to the list of user namespaces in the registration.yml
file provided to the homeserver.
In the example above, you would need to add these lines:
+ - regex: "@feeds:example.com" # Where example.com is your homeserver's domain
+ exclusive: true
+
+
+ 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: https://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 convenience.
publicUrl
should be set to the publicly 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 your 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 recommended +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 to enable Redis:
+queue:
+ monolithic: false
+ port: 6379
+ host: github-bridge-redis
+
+Note that if encryption is enabled, queue.monolithic
must be set to true
, as worker mode is not yet supported with encryption.
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.
+ +Hello there đ. This contributing file is used amongst the matrix.org bridge repositories and should be followed when +making any contribution. If you are reading this, that means you are going to be contributing to some free software, +and that's great! Thank you!
+As a Matrix-based project we use chat rooms heavily for coordinating work. When getting involved with an issue or pull +request, feel free to reach out to us in one of the project rooms. The project room for the repository you are working +on should be visible from the README.md file.
+Be aware that by interacting with our Matrix rooms and/or GitHub repositories, you are agreeing to abide by the +Matrix.org code of conduct.
+We use the GitHub issue tracker for issue filing. 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.Issues will be categorised according to Synapse's rules. To summarise:
+The assigned labels are at the maintainers' discretion, and we will make every effort to be transparent when triaging. +We do not, as a rule, assign priority labeling to issues.
+Documentation is important to us, as bridges are complex beasts and rely on good documentation for both +administrators and users. There are a couple of things to keep in mind when when writing documentation +for bridge projects:
+First of all, thank you for considering making a change to one of our projects. Every change no matter the size makes a difference!
+Each repository contains an eslint
configuration which will dictate the style of the code. All code should be written in
+TypeScript. At time of writing, we target ES2020 (the latest version supported by Node 14). The CI will lint your code automatically,
+but you can save yourself some time by running (yarn lint
/npm lint
) to check locally.
To test your changes, you can run the test
command with either yarn test
or npm test
. Some projects may have additional
+testing constraints noted in the project-specific section below.
Please be aware that reviewers will expect CI to be passing before your changes will be approved, and priority will be given to +PRs that pass CI when reviewing too. If you can't get the CI to pass, please reach out to us either via the PR or in the project +Matrix room (and do not assume that it's always your change that caused the test to fail!).
+As a rule, code does not get merged onto the develop
branch without all CI tests passing.
When making a pull request, please ensure it [the PR] follows these best practises:
+Targets develop
(unless it explicitly depends upon another feature, then depend on that branch and comment to that effect in the PR body).
Is updated via rebase mechanisms when develop
changes, rather than merge commits (reduces noise).
Is signed off. Matrix.org projects require that the +sign off process has been followed in its entirety.
+Has a changelog entry in 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.
+You may be wondering how to determine your GithubPRNumber
number ahead of time. Synapse offers some useful
+hints for this.
Is passing CI. As noted above, please feel free to call out any CI issues you cannot fix.
+Calls out any issue it may fix with a "Fixes #issue-no" in the body.
+When PRs are merged, we will squash the commits down to a single commit. Because of this, do not be afraid to +make multiple commits to a branch rather than amending and force pushing existing commits.
+We aim to review all PRs in a timely manner, though be aware that larger PRs will take more thought.
+We aim to review all PRs from the community promptly, although we can't offer firm time commitments. If you think +your PR has been forgotten and it's been a while, do not hesitate to politely ping in the correct project room.
+When reviewing a PR, a maintainer will:
+This guide aims to cover all bases to get new contributors started, but it won't be able to satisfy every question. If +you have any other questions, please seek us out in any of the project rooms and we will be happy to assist! Other than that, +thanks for taking the time to read this and improving our projects for +the benefit of all đ
+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.