mirror of
https://github.com/matrix-org/matrix-hookshot.git
synced 2025-03-10 21:19:13 +00:00
deploy: 8f2cf779ac4168f12e17e92a26199d8c41e1e64b
This commit is contained in:
Half-Shot
parent
32b73d0c5a
commit
dc2e2047e8
46
print.html
46
print.html
@ -227,7 +227,8 @@ yarn # or npm i
|
||||
<p>Copy the <code>config.sample.yml</code> to a new file <code>config.yml</code>. The sample config is also hosted
|
||||
<a href="./setup/sample-configuration.html">here</a> for your convienence.</p>
|
||||
<p>You should read and fill this in as the bridge will not start without a complete config.</p>
|
||||
<p>You may validate your config without starting the service by running <code>yarn validate-config</code>.</p>
|
||||
<p>You may validate your config without starting the service by running <code>yarn validate-config</code>.
|
||||
For Docker you can run <code>docker run -v /absolute-path-to/config.yml:/config.yml halfshot/matrix-hookshot node Config/Config.js /config.yml</code></p>
|
||||
<p>Copy <code>registration.sample.yml</code> into <code>registration.yml</code> and fill in:</p>
|
||||
<ul>
|
||||
<li>At a minimum, you will need to replace the <code>as_token</code> and <code>hs_token</code> and change the domain part of the namespaces.</li>
|
||||
@ -437,12 +438,10 @@ listeners:
|
||||
<div style="break-before: page; page-break-before: always;"></div><h1 id="setting-up-github"><a class="header" href="#setting-up-github">Setting up GitHub</a></h1>
|
||||
<h2 id="github-app"><a class="header" href="#github-app">GitHub App</a></h2>
|
||||
<p>This bridge requires a <a href="https://github.com/settings/apps/new">GitHub App</a>. You will need to create one.</p>
|
||||
<p>Most of the configuration can be left up to you, but the important points are:</p>
|
||||
<ul>
|
||||
<li>The callback URL should be set if you plan to use OAuth.</li>
|
||||
<li>The webhook URL should point to the public address of your hookshot instance, at the <code>/</code> path. A secret <strong>must</strong> be given.</li>
|
||||
<li>A client secret should be generated and stored.</li>
|
||||
</ul>
|
||||
<h3 id="webhook"><a class="header" href="#webhook">Webhook</a></h3>
|
||||
<p>The <strong>Webhook URL</strong> should point to the public address of your hookshot instance, at the <code>/</code> path.
|
||||
You <strong>MUST</strong> also provide a secret, which should match the <code>github.webhook.secret</code> value in your config.</p>
|
||||
<h3 id="permissions"><a class="header" href="#permissions">Permissions</a></h3>
|
||||
<p>You will need to enable the following permissions:</p>
|
||||
<ul>
|
||||
<li>Repository
|
||||
@ -458,7 +457,7 @@ listeners:
|
||||
</li>
|
||||
<li>Organisation
|
||||
<ul>
|
||||
<li>Discussions (<code>read</code>)</li>
|
||||
<li>Team Discussions (<code>read & write</code>)</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
@ -484,7 +483,7 @@ listeners:
|
||||
</ul>
|
||||
<p>You can disable any of these to disable the events being handled in Hookshot.</p>
|
||||
<p>Once you have setup your app, you can move onto configuring the bridge:</p>
|
||||
<h2 id="configuration-2"><a class="header" href="#configuration-2">Configuration</a></h2>
|
||||
<h2 id="bridge-configuration"><a class="header" href="#bridge-configuration">Bridge Configuration</a></h2>
|
||||
<p>The GitHub service requires a few connection options.</p>
|
||||
<pre><code class="language-yaml">github:
|
||||
auth:
|
||||
@ -500,7 +499,8 @@ listeners:
|
||||
showIssueRoomLink: false
|
||||
</code></pre>
|
||||
<p>In the <code>auth</code> section, you will need to supply the <strong>App ID</strong> given in your GitHub App page.
|
||||
You should also supply the page to a generated private key file.</p>
|
||||
The <code>privateKeyFile</code> can be generated by clicking "Generate a private key" under the <strong>Private keys</strong> section on the GitHub app page.
|
||||
Docker users should store this file alongside <code>config.yml</code> and provide the path <code>/data/github-key.pem</code>.</p>
|
||||
<p>The <code>webhook</code> section takes a secret, which is <strong>Webhook secret</strong> on the GitHub App page.</p>
|
||||
<p>The <code>oauth</code> section should include both the <strong>Client ID</strong> and <strong>Client Secret</strong> on the GitHub App page.
|
||||
The <code>redirect_uri</code> value must be the <strong>public</strong> path to <code>/oauth</code> on the webhooks path. E.g. if your load balancer
|
||||
@ -512,7 +512,7 @@ are supported.</p>
|
||||
<p>If you have followed these steps correctly, GitHub should now be configured with hookshot 🥳.</p>
|
||||
<p>You can now follow the guide on <a href="setup/../usage/auth.html">authenticating with GitHub</a>, and then <a href="setup/../usage/room_configuration/github_repo.html#setting-up">bridging a room</a></p>
|
||||
<div style="break-before: page; page-break-before: always;"></div><h1 id="gitlab"><a class="header" href="#gitlab">GitLab</a></h1>
|
||||
<h2 id="configuration-3"><a class="header" href="#configuration-3">Configuration</a></h2>
|
||||
<h2 id="configuration-2"><a class="header" href="#configuration-2">Configuration</a></h2>
|
||||
<p>GitLab configuration is fairly straight-forward:</p>
|
||||
<pre><code class="language-yaml"> # (Optional) Configure this to enable GitLab support
|
||||
#
|
||||
@ -525,10 +525,12 @@ are supported.</p>
|
||||
<p>You need to list all the instances you plan to connect to in the <code>config.yml</code>. This is
|
||||
used so that users can give a short name like <code>gitlab</code> or <code>matrix.org</code> when they want
|
||||
to specify an instance.</p>
|
||||
<p>The webhooks secret should be generated, for use in your repositories.</p>
|
||||
<p>You should generate a webhook <code>secret</code> (e.g. <code>pwgen -n 64 -s 1</code>) and then use this as your
|
||||
"Secret token" when adding webhooks.</p>
|
||||
<h2 id="adding-a-repository"><a class="header" href="#adding-a-repository">Adding a repository</a></h2>
|
||||
<p>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 <code>/</code> path.</p>
|
||||
<p>You should use the value of <code>webhook.secret</code> from your config as your "Secret token".</p>
|
||||
<p>You should add the events you wish to trigger on. Hookshot currently supports:</p>
|
||||
<ul>
|
||||
<li>Push events</li>
|
||||
@ -562,12 +564,14 @@ Support for on-prem deployments is hoping to land soon.
|
||||
<p>You will need a Atlassian account with the ability to use the developer tools in order to create the app.</p>
|
||||
<p>You'll first need to head to https://developer.atlassian.com/console/myapps/create-3lo-app/ to create a
|
||||
"OAuth 2.0 (3LO)" integration.</p>
|
||||
<p>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 <code>/jira/oauth</code>.
|
||||
- Copy the client ID and Secret from Settings</p>
|
||||
<h2 id="configuration-4"><a class="header" href="#configuration-4">Configuration</a></h2>
|
||||
<p>Once named and created, you will need to:</p>
|
||||
<ol>
|
||||
<li>Enable the User REST, Jira Platform REST and User Identity APIs under Permissions.</li>
|
||||
<li>Use rotating tokens under Authorisation.</li>
|
||||
<li>Set a callback url. This will be the public URL to hookshot with a path of <code>/jira/oauth</code>.</li>
|
||||
<li>Copy the client ID and Secret from Settings</li>
|
||||
</ol>
|
||||
<h2 id="configuration-3"><a class="header" href="#configuration-3">Configuration</a></h2>
|
||||
<p>You can now set some configuration in the bridge <code>config.yml</code></p>
|
||||
<pre><code class="language-yaml">jira:
|
||||
webhook:
|
||||
@ -577,7 +581,7 @@ Support for on-prem deployments is hoping to land soon.
|
||||
client_secret: your-client-secret
|
||||
redirect_uri: https://example.com/hookshot/jira/oauth
|
||||
</code></pre>
|
||||
<p>You can leave the <code>oauth</code> section blank if you are not planning to use those capabilities.</p>
|
||||
<p>You can omit the <code>oauth</code> section if you are not planning to allow users to login and use interactive features (i.e. webhook only mode).</p>
|
||||
<p>The <code>redirect_uri</code> value must be the <strong>public</strong> path to <code>/jira/oauth</code> on the webhooks path. E.g. if your load balancer
|
||||
points <code>https://example.com/hookshot</code> to the bridge <code>webhooks</code> listener, you should use the path <code>https://example.com/hookshot/jira/oauth</code>.
|
||||
This value MUST exactly match the <strong>Callback URL</strong> on the JIRA integration page page.</p>
|
||||
@ -587,7 +591,7 @@ This value MUST exactly match the <strong>Callback URL</strong> on the JIRA inte
|
||||
<div style="break-before: page; page-break-before: always;"></div><h1 id="webhooks"><a class="header" href="#webhooks">Webhooks</a></h1>
|
||||
<p>Hookshot supports generic webhook support so that services can send messages into Matrix rooms without being aware of the Matrix protocol. This works
|
||||
by having services hit a unique URL that then transforms a HTTP payload into a Matrix message.</p>
|
||||
<h2 id="configuration-5"><a class="header" href="#configuration-5">Configuration</a></h2>
|
||||
<h2 id="configuration-4"><a class="header" href="#configuration-4">Configuration</a></h2>
|
||||
<p>You will need to add the following configuration to the config file.</p>
|
||||
<pre><code class="language-yaml">generic:
|
||||
enabled: true
|
||||
@ -948,7 +952,7 @@ a new release.</p>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
<h2 id="configuration-6"><a class="header" href="#configuration-6">Configuration</a></h2>
|
||||
<h2 id="configuration-5"><a class="header" href="#configuration-5">Configuration</a></h2>
|
||||
<p>This connection supports a few options which can be defined in the room state:</p>
|
||||
<table><thead><tr><th>Option</th><th>Description</th><th>Allowed values</th><th>Default</th></tr></thead><tbody>
|
||||
<tr><td>ignoreHooks</td><td>Choose to exclude notifications for some event types</td><td>Array of: <a href="usage/room_configuration/github_repo.html#supported-event-types">Supported event types</a></td><td><em>empty</em></td></tr>
|
||||
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@ -181,7 +181,8 @@ yarn # or npm i
|
||||
<p>Copy the <code>config.sample.yml</code> to a new file <code>config.yml</code>. The sample config is also hosted
|
||||
<a href="./setup/sample-configuration.html">here</a> for your convienence.</p>
|
||||
<p>You should read and fill this in as the bridge will not start without a complete config.</p>
|
||||
<p>You may validate your config without starting the service by running <code>yarn validate-config</code>.</p>
|
||||
<p>You may validate your config without starting the service by running <code>yarn validate-config</code>.
|
||||
For Docker you can run <code>docker run -v /absolute-path-to/config.yml:/config.yml halfshot/matrix-hookshot node Config/Config.js /config.yml</code></p>
|
||||
<p>Copy <code>registration.sample.yml</code> into <code>registration.yml</code> and fill in:</p>
|
||||
<ul>
|
||||
<li>At a minimum, you will need to replace the <code>as_token</code> and <code>hs_token</code> and change the domain part of the namespaces.</li>
|
||||
|
||||
@ -153,12 +153,10 @@
|
||||
<h1 id="setting-up-github"><a class="header" href="#setting-up-github">Setting up GitHub</a></h1>
|
||||
<h2 id="github-app"><a class="header" href="#github-app">GitHub App</a></h2>
|
||||
<p>This bridge requires a <a href="https://github.com/settings/apps/new">GitHub App</a>. You will need to create one.</p>
|
||||
<p>Most of the configuration can be left up to you, but the important points are:</p>
|
||||
<ul>
|
||||
<li>The callback URL should be set if you plan to use OAuth.</li>
|
||||
<li>The webhook URL should point to the public address of your hookshot instance, at the <code>/</code> path. A secret <strong>must</strong> be given.</li>
|
||||
<li>A client secret should be generated and stored.</li>
|
||||
</ul>
|
||||
<h3 id="webhook"><a class="header" href="#webhook">Webhook</a></h3>
|
||||
<p>The <strong>Webhook URL</strong> should point to the public address of your hookshot instance, at the <code>/</code> path.
|
||||
You <strong>MUST</strong> also provide a secret, which should match the <code>github.webhook.secret</code> value in your config.</p>
|
||||
<h3 id="permissions"><a class="header" href="#permissions">Permissions</a></h3>
|
||||
<p>You will need to enable the following permissions:</p>
|
||||
<ul>
|
||||
<li>Repository
|
||||
@ -174,7 +172,7 @@
|
||||
</li>
|
||||
<li>Organisation
|
||||
<ul>
|
||||
<li>Discussions (<code>read</code>)</li>
|
||||
<li>Team Discussions (<code>read & write</code>)</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
@ -200,7 +198,7 @@
|
||||
</ul>
|
||||
<p>You can disable any of these to disable the events being handled in Hookshot.</p>
|
||||
<p>Once you have setup your app, you can move onto configuring the bridge:</p>
|
||||
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
|
||||
<h2 id="bridge-configuration"><a class="header" href="#bridge-configuration">Bridge Configuration</a></h2>
|
||||
<p>The GitHub service requires a few connection options.</p>
|
||||
<pre><code class="language-yaml">github:
|
||||
auth:
|
||||
@ -216,7 +214,8 @@
|
||||
showIssueRoomLink: false
|
||||
</code></pre>
|
||||
<p>In the <code>auth</code> section, you will need to supply the <strong>App ID</strong> given in your GitHub App page.
|
||||
You should also supply the page to a generated private key file.</p>
|
||||
The <code>privateKeyFile</code> can be generated by clicking "Generate a private key" under the <strong>Private keys</strong> section on the GitHub app page.
|
||||
Docker users should store this file alongside <code>config.yml</code> and provide the path <code>/data/github-key.pem</code>.</p>
|
||||
<p>The <code>webhook</code> section takes a secret, which is <strong>Webhook secret</strong> on the GitHub App page.</p>
|
||||
<p>The <code>oauth</code> section should include both the <strong>Client ID</strong> and <strong>Client Secret</strong> on the GitHub App page.
|
||||
The <code>redirect_uri</code> value must be the <strong>public</strong> path to <code>/oauth</code> on the webhooks path. E.g. if your load balancer
|
||||
|
||||
@ -164,10 +164,12 @@
|
||||
<p>You need to list all the instances you plan to connect to in the <code>config.yml</code>. This is
|
||||
used so that users can give a short name like <code>gitlab</code> or <code>matrix.org</code> when they want
|
||||
to specify an instance.</p>
|
||||
<p>The webhooks secret should be generated, for use in your repositories.</p>
|
||||
<p>You should generate a webhook <code>secret</code> (e.g. <code>pwgen -n 64 -s 1</code>) and then use this as your
|
||||
"Secret token" when adding webhooks.</p>
|
||||
<h2 id="adding-a-repository"><a class="header" href="#adding-a-repository">Adding a repository</a></h2>
|
||||
<p>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 <code>/</code> path.</p>
|
||||
<p>You should use the value of <code>webhook.secret</code> from your config as your "Secret token".</p>
|
||||
<p>You should add the events you wish to trigger on. Hookshot currently supports:</p>
|
||||
<ul>
|
||||
<li>Push events</li>
|
||||
|
||||
@ -166,11 +166,13 @@ Support for on-prem deployments is hoping to land soon.
|
||||
<p>You will need a Atlassian account with the ability to use the developer tools in order to create the app.</p>
|
||||
<p>You'll first need to head to https://developer.atlassian.com/console/myapps/create-3lo-app/ to create a
|
||||
"OAuth 2.0 (3LO)" integration.</p>
|
||||
<p>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 <code>/jira/oauth</code>.
|
||||
- Copy the client ID and Secret from Settings</p>
|
||||
<p>Once named and created, you will need to:</p>
|
||||
<ol>
|
||||
<li>Enable the User REST, Jira Platform REST and User Identity APIs under Permissions.</li>
|
||||
<li>Use rotating tokens under Authorisation.</li>
|
||||
<li>Set a callback url. This will be the public URL to hookshot with a path of <code>/jira/oauth</code>.</li>
|
||||
<li>Copy the client ID and Secret from Settings</li>
|
||||
</ol>
|
||||
<h2 id="configuration"><a class="header" href="#configuration">Configuration</a></h2>
|
||||
<p>You can now set some configuration in the bridge <code>config.yml</code></p>
|
||||
<pre><code class="language-yaml">jira:
|
||||
@ -181,7 +183,7 @@ Support for on-prem deployments is hoping to land soon.
|
||||
client_secret: your-client-secret
|
||||
redirect_uri: https://example.com/hookshot/jira/oauth
|
||||
</code></pre>
|
||||
<p>You can leave the <code>oauth</code> section blank if you are not planning to use those capabilities.</p>
|
||||
<p>You can omit the <code>oauth</code> section if you are not planning to allow users to login and use interactive features (i.e. webhook only mode).</p>
|
||||
<p>The <code>redirect_uri</code> value must be the <strong>public</strong> path to <code>/jira/oauth</code> on the webhooks path. E.g. if your load balancer
|
||||
points <code>https://example.com/hookshot</code> to the bridge <code>webhooks</code> listener, you should use the path <code>https://example.com/hookshot/jira/oauth</code>.
|
||||
This value MUST exactly match the <strong>Callback URL</strong> on the JIRA integration page page.</p>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user