Skip to main content

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.

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.

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.

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.

The upstream repositories, messages, and documents remain. Materialized diagnostic output, worker-input copies, and broker messages expire within their documented bounded retention windows. Provider cleanup is best effort. If local erasure fails, the connection remains unchanged, and you can retry the disconnect. If the provider is unreachable, the mirror still erases and the connection disconnects. You may then need to remove an app installation, token, or webhook Hephaestus created at the provider.

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.