Manage workspace integrations

This page is for workspace admins. Instance operators configure provider apps and deployment settings in Integration settings. Account linking belongs in User settings.

GitHub

GitHub integration owns app setup and permissions. See Repositories for repository monitoring and removal.

1. Install the GitHub App for the organization or use a personal access token connection.
2. For an App connection, manage repository access in the GitHub installation.
3. For a token-managed connection, open Administration → Integrations → GitHub → Manage repositories → Add a repository.

Before Hephaestus adds a repository, it asks GitHub whether the connection's own token can read it. Another workspace that synced the same repository does not change this result. Hephaestus adds repositories this way only for a token connection on github.com.

GitLab

A deployment syncs one GitLab instance. Create workspace lets an eligible user select a group on that configured instance, using their connected GitLab account and an access token. A login provider for a different instance permits sign-in, but does not permit a workspace there.

More than one GitLab

Version 1.0 supports one GitLab instance per install. You cannot add a second instance to an install. If your organization has two GitLab instances, run one Hephaestus install for each instance, each with its own release name, database, and host name. Installs share no data, so each person has a separate account and separate practice pages on each install.

GitLab Community Edition

GitLab Community Edition has no group webhooks, and Hephaestus registers only group webhooks. Thus, registration fails on Community Edition and on any group without the Premium tier. The sync then reports as incomplete, with a reason that names the Owner role and the Premium tier. You see this reason even if you are an Owner. Do not create a project webhook instead: Hephaestus accepts only the webhooks that it registers.

Hephaestus still works, but it sees changes only when a sync runs:

• The scheduled sync (SYNC_CRON, hourly by default) reads new and changed work.
• Sync now on the connection runs a sync at once.
• A person can request a review only of work that a sync has read.
• Feedback delivery does not depend on webhooks. Hephaestus still posts its comments through the GitLab API.

If new work must appear sooner, schedule the sync more often.

Create a workspace

The user also chooses which projects the workspace monitors. All projects monitors every project of the group and its subgroups, including projects added later. Selected projects monitors only the chosen projects. Hephaestus checks each chosen project with the user's token. With All projects, workspace members come from the whole group. With Selected projects, a person becomes a workspace member only when one of these grants them access:

• A chosen project.
• A subgroup between the connected group and a chosen project.

Access through the connected group or one of its parent groups alone does not make a person a member. A member who is an admin of the connected group stays a workspace admin. A Maintainer of a project or subgroup becomes a member, not an admin. Guest access to a chosen project alone does not make a person a member. Workspace owners always stay. Teams still come from the whole group.

Membership changes apply at the next successful sync, or when you select Sync now. If GitLab does not list a chosen project or subgroup completely, Hephaestus keeps the current members.

To change the choice later, open Administration → Integrations → GitLab → Projects to follow. This setting is available only while the GitLab connection is active.

• Only the projects listed below keeps the current monitored projects. Hephaestus adds no new projects from the group. The list can be empty.
• All projects in the group lets Hephaestus add the projects that it finds in the group at its next check. Hephaestus asks you to confirm this change. Stopped projects stay stopped.

Neither change removes synced work or changes membership in GitLab. Workspace members follow the new choice at the next successful sync. Use Add a repository and Stop monitoring to change the list. If the connection or its projects change during the save, Hephaestus keeps the earlier choice. Then choose again.

Hephaestus automatically registers group hooks with a signed routing token bound to the connection. Do not replace that token with WEBHOOK_SECRET.

1. Open Administration → Integrations → GitLab → Manage repositories → Add a repository.
2. Add the project by its full namespace path.

Before Hephaestus adds the project, it asks GitLab whether the connection's own token can read it. If the connection changes during the check, Hephaestus adds nothing. Then add the project again.

The connection shows token expiry. Hephaestus checks the token each day and rotates it before expiry when GitLab permits it. If it cannot rotate the token, use Personal access token → Replace token. This keeps repositories and stored work. Optional connection-alert emails report problems and recovery.

Token checks, rotation, and replacement keep explicit project stops. Use Add a repository to resume a stopped project. A stopped project keeps its synced work under Stopped projects until a workspace admin selects Remove synced work while the connection is active. Repositories describes both actions. Disconnect stays the separate action that erases the whole mirror of the connection.

GitLab reconciliation removes deleted issue and merge-request notes, including diff notes. Removal requires a complete listing and a direct check that each missing note is gone. An incomplete listing removes nothing for that parent. Do not expect every deletion to arrive as a webhook.

Slack

Members must separately link their Slack accounts to use Hephaestus in direct messages. Monitoring starts after a visible announcement is posted.

1. Open Administration → Integrations → Slack.
2. Connect the Slack workspace through OAuth.
3. Use the channel picker to add channels for monitoring.

Channel monitoring and a member's permission to use their messages are separate: User settings → Slack lets members control their new channel messages. The workspace connection does not override a member's AI choice.

Use Reconnect Slack with the same Slack workspace to replace a bot token without removing channels, their consent, mirrored messages, or retention settings. Do not use Disconnect Slack for this.

The Slack page asks Slack which scopes the bot token holds. If the token lacks a scope that Hephaestus requests, the page shows Permissions missing and names each scope. A token keeps the scopes of the authorization that created it. Thus, a Slack app installed before Hephaestus requested a scope lacks it until you reconnect.

1. Apply the current Slack app manifest, as Update an existing Slack app tells.
2. Use Reconnect Slack with the same Slack workspace.
3. Open the Slack page again. It shows Connected when the token holds every scope.

Outline

Hephaestus reads the selected collections. It does not write documents to Outline. Members can link their own Outline accounts to attribute authored documents. A workspace admin cannot approve a new Outline operator through its URL.

1. Open Administration → Integrations → Outline.
2. Enter an operator-approved HTTPS origin and an API key.
3. Register the collections to mirror.

Replace an Outline key without erasing the mirror

The current UI has no key-replacement form for an existing connection. Disconnect Outline erases the mirror.

CAUTION: Outline key secrecy and connection identity

Keep the key out of shell history, logs, and support tickets. Use the same origin and a key that belongs to the same Outline team. Do not change the origin or team during key rotation.

1. To keep the mirror, create a valid API key in Outline.

2. As a workspace admin, send this authenticated request to the application server's existing connection API with normal CSRF protection:

   POST /api/workspaces/{workspaceSlug}/connections
   Content-Type: application/json
   
   {
     "kind": "OUTLINE",
     "userInput": {
       "server_url": "https://wiki.example.com",
       "token": "<new API key>"
     }
   }

3. Check that the response's connection ID matches the existing connection.

4. Check webhook registration.

5. Use Sync now to verify that collections refresh.

6. Revoke the old key only after that check succeeds.

The API validates the key and updates the connection's credentials without deletion of documents or collection registrations. It resets connection configuration, including subscription metadata.

Workspace roles from GitHub and GitLab

The organization or group roster of a GitHub or GitLab connection sets workspace roles at each sync:

Provider	Admin	Member
GitHub organization	Organization owner	Organization member, or a member of one of its teams
GitLab group	Owner or Maintainer	Developer, Reporter, Planner, Guest or Minimal access

Sync never sets or removes the Owner role. Slack and Outline set no workspace roles.

Members shows where each role comes from:

• From GitHub or From GitLab: the next sync can change the role.
• Set in Hephaestus: an admin set the role on this page. Sync does not change it.

If you change a role on Members, the role is set in Hephaestus. To let the provider set it again, select Use GitHub role or Use GitLab role in the member's row. The role changes at the next sync. Select Sync now on the connection to apply it at once. An owner's role is always set in Hephaestus. To let the provider set it, give the person another role first.

A role set in Hephaestus does not keep the membership. If the provider no longer lists the person, they leave the workspace at the next sync. If they come back, their role comes from the provider again.

Check that it worked

1. Open the page of the integration under Administration → Integrations.
2. Open its resource sync table. No resource shows a last error. If one does, follow Read sync errors.
3. For Slack, check that the page shows Connected.

Read sync errors

A healthy connection does not prove that every resource synced. An error clears only when its affected sync path succeeds. A skipped pass keeps the error.

1. For repositories, open Administration → Integrations → GitHub/GitLab → Manage repositories.
2. For Slack channels or Outline collections, open that integration's page.
3. Open its resource sync table.
4. Read the affected resource's last error.
5. Correct access or configuration.
6. Select Sync now on the connection.

A repository reported as Repository not found or not accessible may have moved or lost access. The mirror stays. After two consecutive unavailable responses, automatic rechecks run at most once in 24 hours. Sync now checks immediately. See Unavailable repositories.

Disconnect is an erase

Disconnect permanently erases the integration's mirrored data in this workspace before it attempts provider cleanup. A workspace purge erases it too. Reconnecting does not restore that data: a reconnect performs a fresh initial sync.

• GitHub and GitLab: repository mirrors and their associated synced work.
• Slack: mirrored messages, threads, channel records, and associated consent records. It also erases every Hephaestus message of a Slack turn: the questions from Slack and Hephaestus's answers to them. It stops the answers that still run.
• Outline: mirrored documents, collection registrations, and document events.

For each integration, the disconnect also erases the practice results and the feedback that Hephaestus derived from that work.

The upstream repositories, messages, and documents remain. Materialized diagnostic output, attempt-input copies, and inbox events expire within their documented bounded retention windows. If local erasure fails, the connection remains unchanged, and you can retry the disconnect.

After the disconnect commits, Hephaestus removes what it created at the provider:

Integration	What Hephaestus removes at the provider
GitHub	The GitHub App installation, if no other Hephaestus workspace uses it
GitLab	The group webhook. GitLab lets only you revoke the access token, so revoke it in GitLab.
Slack	The bot token, if no other Hephaestus workspace is connected to the same Slack workspace
Outline	The webhook subscription. Revoke the API key in Outline.

A disconnected connection keeps its encrypted credential for at most 24 hours so cleanup can use it. Erasure can remove it earlier. The removal record keeps no credential, provider payload or signed callback URL.

Hephaestus records removal before sending it to the provider. Every retry reads the captured resource and checks its ownership before DELETE. A new connection cannot reuse an identity while an earlier removal can still affect it.

GitLab and Outline register a fresh hook or subscription when you resume or reconnect. GitHub needs a distinct installation while removal is unresolved. Slack blocks both the exact token and its bot user: a different token for the same bot user is not enough. A bot token's revocation does not uninstall the Slack app.

Confirm a provider removal

Each integration page has Provider removals. It shows waiting removals, missing authorization and operations that need explicit confirmation. Workspace admins can inspect their connection's repairs. Only an instance admin can release a block.

1. Check at the provider that the old resource is gone and its uncertain removal can no longer affect a replacement. A timeout, 202, or later absence alone does not prove that an earlier DELETE cannot still finish.
2. Open the connection's integration administration page.
3. Select Confirm removal for the exact provider identity.
4. Confirm that you checked at the provider, then select Release block.

The action records the admin, connection and confirmation in each referencing workspace’s audit log. An authorization or registration that is still in progress cannot be released. An uncertain Slack authorization remains visible even if the process stopped before it stored the token identity. It does not restore erased work or resume a failed authorization flow. Start the connection flow again after release. For Slack, release a pending token removal before its related bot-user block.

Instance admins can also open Instance administration → Provider removals. A repair remains there after its connection or workspace is deleted. Release an orphan there by its exact provider identity. Hephaestus does not restore the deleted ownership link. Unresolved identifiers can remain indefinitely until resolution or release. The personal-data map states what is retained and why.

A connection with its integration disabled instance-wide cannot disconnect until the integration is enabled again. Nothing else can erase its mirror. See erasure triggers in the personal-data map.

1. Inspect provider-side app access, hooks, and keys separately.
2. To repair a credential, use the replacement paths above or Credential key rotation, not Disconnect.

Reconnect GitLab

Open Administration → Integrations, then open GitLab. Enter a new token and select Reconnect GitLab. Hephaestus verifies that the token can read the same group before it restores the connection. If the workspace used Selected projects, select those projects again after reconnecting. The previous mirror was erased. The connection syncs the work again.