Connect Outline
Approve the Outline instances that workspaces may mirror, register the Outline OAuth application, and turn on Outline in the Helm chart.
Turn on Outline so that workspace admins can mirror Outline collections into a workspace. Practice reviews and conversations then use the mirrored documents as context. You approve each Outline instance by its origin. A workspace admin cannot approve one by entering its address. After this setup, a workspace admin connects Outline in the web app, as Connect Slack and Outline to a workspace describes.
Before you start
- An installed instance that serves its host over HTTPS (Install on Kubernetes).
- The HTTPS origin of each Outline instance, such as
https://wiki.example.com, on a public address. - For each origin, the entry in the processor checklist: legal role, hosting region, transfer basis, retention terms and processing agreement.
- Optional: the admin role in Outline, to register the OAuth application that links member accounts.
kubectlwith access to the release namespace, andjq.
The commands use the release namespace hephaestus and the release Secret hephaestus-app.
Replace these names if your release uses other names.
Register the Outline OAuth application
Members use this application to link their Outline account, so that Hephaestus knows who wrote a document. Without it, workspaces mirror collections, but Hephaestus cannot match a document to the member who wrote it.
- In Outline, open Settings → Applications, and add an application.
- Set Redirect URI to
https://<host>/api/login/oauth2/code/outline, without a final slash. Outline compares the address exactly. - Set the scope to
read. - Save the application.
- Copy its client ID and client secret.
Set the Helm values and Secret keys
-
Optional: type the client secret of the OAuth application. The shell does not show it:
read -rs OUTLINE_OAUTH_CLIENT_SECRET && export OUTLINE_OAUTH_CLIENT_SECRET -
Optional: add the client secret to the release Secret:
jq -n --arg secret "$OUTLINE_OAUTH_CLIENT_SECRET" '{stringData: {OUTLINE_OAUTH_CLIENT_SECRET: $secret}}' | kubectl -n hephaestus patch secret hephaestus-app --type merge --patch-file /dev/stdin -
Add Outline to
site.yaml:config: outline: enabled: true allowedOrigins: - https://wiki.example.com oauthBaseUrl: https://wiki.example.com oauthClientId: 0123456789abcdef oauthDisplayName: Example wikiValue What it sets Default config.outline.enabledThe Outline connection, its sync, and its webhook receiver falseconfig.outline.allowedOriginsThe HTTPS origins that a workspace can connect to Empty config.outline.oauthBaseUrlThe Outline instance of the OAuth application. Required with oauthClientId.Empty config.outline.oauthClientIdThe client ID of the OAuth application. Empty creates no account linking. Empty config.outline.oauthDisplayNameThe name on the account-linking button OutlineAn origin has no path, query, fragment or user name. An origin on a private or site-local address is refused. The server does not start with an entry that is not valid. While
config.outline.enabledisfalse, the Outline page of each workspace says that Outline is not enabled on this instance. -
Apply
site.yaml. On a cluster, run thehelm upgradecommand of Install again. On one host, run the installer again (Run the installer).
At its next start, the server creates the Outline login provider if it does not exist.
If oauthBaseUrl is empty or not valid, the server logs the reason at ERROR and creates no provider.
After that, the server ignores the client ID and secret of the chart.
An instance admin can add or change the provider under Instance administration → Login providers.
Check that it worked
- In a workspace, open Administration → Integrations. The sidebar lists Outline.
- Open Outline.
- Enter an approved origin as Server URL, and an Outline API key as API token.
- Select Connect Outline.
- Add a collection. Its documents show after the first sync.
When a workspace connects, Hephaestus registers a webhook subscription in Outline.
Its address is https://<host>/webhooks/outline/…, so Outline must reach your host.
WEBHOOK_ROUTING_SECRET signs each subscription, and you set nothing for it.
Undo
- In each workspace with an Outline connection, select Disconnect Outline if its mirror must be erased. A connection cannot disconnect while Outline is off for the instance.
- Set
config.outline.enabledtofalseinsite.yaml. - Apply
site.yaml.
With Outline off, the receiver answers 404 to each Outline delivery.
Outline turns off a subscription after 25 failed deliveries.
To withdraw one Outline instance only, remove its origin from config.outline.allowedOrigins and apply site.yaml.
Its connections then stop their sync, webhooks, account linking and review context.
Their mirror stays until a workspace admin disconnects them.