Connect Slack and Outline to a workspace
Connect Slack and Outline to your workspace, choose the channels and collections that Hephaestus reads, and disconnect them.
Connect Slack so that members can talk with Hephaestus in direct messages, and choose the channels that Hephaestus reads. Connect Outline so that practice reviews can use your design documents and decision records. Workspace admins and owners do these tasks under Administration → Integrations.
Slack and Outline in a workspace
Your instance operator turns on Slack and Outline for the whole instance. If Integrations does not list Slack or Outline, ask your instance operator to turn it on.
A Slack connection lets each member send Hephaestus direct messages. To do so, a member also connects their own Slack account in User settings. Hephaestus stores no channel message until you activate the channel. Each member decides if Hephaestus uses their messages in monitored channels, as User settings → Slack describes. The workspace connection does not change the AI choice of a member.
An Outline connection mirrors the collections that you choose. Hephaestus reads them and never writes to Outline, so it posts no feedback there. Feedback about a document goes to the Practice profile of its author, and to their conversation with Hephaestus. Members can connect their Outline account in User settings, so that Hephaestus knows which documents they wrote.
Connect Slack
- Under Administration → Integrations, open Slack.
- Select Connect Slack workspace.
- In Slack, allow the Hephaestus app.
Slack returns you to Hephaestus, and the page shows Connected. Finish the connection in the same browser where you started it.
Monitor a Slack channel
- On the Slack page, select Add channel.
- Choose a channel from the list, or paste a channel link or ID.
- Select Add channel. The channel shows Not started.
- Open the actions menu of the channel, and select Activate monitoring….
- Read the dialog, then select Activate monitoring.
Hephaestus posts a visible announcement in the channel. While Slack confirms the announcement, the channel shows Activating, and Hephaestus reads no messages. When Slack confirms it, the channel shows Monitoring, and Hephaestus reads only the messages after the announcement. It never reads older messages.
If Slack cannot confirm the announcement, the channel shows Activation failed. Check that Slack is still connected and that the Hephaestus app is still in the channel, then select Retry activation. A retry first looks for the earlier announcement, so it does not post a second one. If the retry still fails, check that the app can read the channel history, or remove the channel and add it again. Messages from the time that monitoring was off stay unread.
You can remove a channel while it activates. An announcement that Slack is already posting can still appear, but monitoring stays off.
Hephaestus posts no practice feedback in monitored channels or their threads. Feedback about a channel thread goes to the Practice profile of its author, and to their conversation with Hephaestus.
In the actions menu of a channel, Pause stops reading and Resume starts again. Remove and erase… removes the channel and erases the messages that Hephaestus stored from it.
Reconnect Slack
Reconnect Slack to replace its token, or to grant the permissions that the Slack page names as missing. Reconnecting keeps the channels, their consent, the stored messages, and their retention.
- On the Slack page, select Reconnect Slack.
- In Slack, choose the same Slack workspace.
The page shows Connected when the token holds every permission. If it shows Permissions missing, it names each missing permission. Ask your instance operator to update the Slack app, then select Reconnect Slack again.
Connect Outline
- In Outline, create an API key for a dedicated bot user under Settings → API Keys.
- In Hephaestus, under Administration → Integrations, open Outline.
- Enter the address of your Outline in Server URL.
- Enter the key in API token.
- Select Connect Outline.
- Select Add collection.
- Select the collections to mirror, then select the Add button.
The documents of each collection appear after its first sync. In the actions menu of a collection, Pause and Resume stop and start its sync. Remove and erase… removes the collection and erases its mirrored documents.
Your instance operator approves each Outline address. If Hephaestus does not accept your address, ask your instance operator to approve it.
Replace the Outline API key
Outline API keys do not renew. The Outline page shows when the key expires, and says so when Outline no longer accepts it. Replace the key on the connection you have. Do not use Disconnect Outline, which erases the mirror.
- In Outline, create an API key for the same Outline team under Settings → API Keys.
- In Hephaestus, under Administration → Integrations, open Outline.
- Enter the key in Replace API key, then select Replace key.
- Check that the page shows Outline accepts this key.
- Select Sync now and check that the collections refresh.
- Revoke the old key in Outline.
The connection, its collections and its mirrored documents stay. Hephaestus refuses a key of another Outline team. Replace API key shows only while the connection is active. Resume a suspended connection first.
Disconnect an integration
Disconnecting erases the data that Hephaestus stored for the integration in this workspace. Reconnecting does not restore it, and starts a new first sync.
| Integration | Hephaestus erases | Hephaestus removes at the provider |
|---|---|---|
| GitHub | The repository mirror and the work synced from it | The GitHub App installation. For a token-managed workspace, revoke the token in GitHub yourself. |
| GitLab | The repository mirror and the work synced from it | Nothing yet: the group webhook, or the webhook of each project, stays in GitLab. Delete it in GitLab under Settings → Webhooks, then ask an instance admin to release its block under Provider removals. Revoke the access token in GitLab yourself. |
| Slack | Stored messages, threads, channels and their consent records. Every question from Slack and its answer. | The bot token, if no other Hephaestus workspace uses the same Slack workspace |
| Outline | Mirrored documents, collections and document events | The webhook subscription. Revoke the API key in Outline yourself. |
Hephaestus also erases the practice results and the feedback that came from this data. Repositories, messages, and documents at the provider stay.
To disconnect Slack or Outline:
- Under Administration → Integrations, open Slack or Outline.
- Select Disconnect Slack… or Disconnect Outline….
- Read the dialog, then select Disconnect Slack or Disconnect Outline.
To replace only the Slack token, use Reconnect Slack instead. If your instance operator turned the integration off, you cannot disconnect it until it is on again.
Administration → Integrations has no disconnect for GitHub or GitLab. If you uninstall the Hephaestus GitHub App on GitHub, Hephaestus deletes the whole workspace.
Provider removals
When a connection ends, Hephaestus removes what it created at the provider. If Hephaestus cannot be sure that a removal finished, it blocks the old resource, so that a new connection cannot use it. Each integration page lists these blocks under Provider removals. Only an instance admin can release a block, as Provider removals describes. Releasing a block does not restore erased work.
Troubleshooting
Slack or Outline is missing under Integrations
Your instance operator has not turned it on. Ask them to follow Connect Slack or Connect Outline.
A channel or a collection shows a sync error
Read A connection shows a sync error.
GitLab shows "New work shows only after a sync"
GitLab refused every webhook that Hephaestus tried to register. Hephaestus still syncs your GitLab work, but changes show only after the scheduled sync or Sync now.
- In GitLab, give the account of the workspace token the Owner role on the group. GitLab Community Edition and the Free tier have no group webhooks. There, the Maintainer role on each project is enough, and Hephaestus adds a webhook to each project.
- Wait up to 6 hours: Hephaestus then tries again. The notice goes away when a webhook works.
Your instance operator can read more in GitLab without group webhooks.