Integrations

Integrations connect your workspace to external services like GitHub, GitLab, Slack, and PagerDuty. You set up a connection once, and CodeHerder stores the credential encrypted and keeps it available for the workspace to use. What it’s used for depends on the provider: see What each connection does before you connect one.

Where to find it

Open Admin → Integrations in the sidebar. It’s a web app feature — there’s no ch command for managing integrations.

Who can manage integrations

Only workspace owners and admins can connect, edit, test, or remove an integration. Other members see a read-only view of the catalog and any existing connections, with a banner explaining that management requires owner or admin access.

The provider catalog

The Integrations page shows a catalog of providers you can connect. Today, four are available:

• GitHub — connect to a GitHub host or organization with a personal access token.
• GitLab — connect to a GitLab host or group with a personal access token.
• Slack — connect a Slack workspace by authorizing CodeHerder.
• PagerDuty — connect a PagerDuty account with an Events API routing key.

CodeHerder adds more providers over time — check back on the Integrations page to see what’s currently available.

You can have at most one connection per provider per workspace, and connecting a second one is refused. A group’s connection is also usable by every workspace nested beneath it. See Inherited connections.

What each connection does

What happens after you connect depends on which provider you pick.

GitHub and GitLab

A GitHub or GitLab connection lets CodeHerder check the status of a merge request (for example, to notice it has merged) when a task is parked at a workflow stage built to wait for someone else to merge it. CodeHerder normally learns about a merge on its own; this connection is a way to catch up if that update doesn’t arrive.

This only matters for a workflow that has such a waiting stage. None of CodeHerder’s built-in task types do: their own merge stage lands the merge request itself, so by default a GitHub or GitLab connection just sits there, stored but unused. That changes as soon as a workspace customizes a task type’s workflow to add a stage that waits on an external merge (see Customising task types and workflows).

When a task does reach such a stage:

• A connection and a recorded merge-request link are both required to enter it. Without an enabled connection for the merge request’s host, or without a merge-request link recorded on the task (ch task set-merge-ref <task> <pr-or-mr-url>), CodeHerder refuses the advance and tells you which one is missing.
• The connection’s host must match the merge request’s host. A GitHub connection checks GitHub merge requests, a GitLab connection checks GitLab ones. Self-hosted works too: a GitHub Enterprise Server or GitLab instance, as long as CodeHerder can reach it over HTTPS.
• Disabling the connection turns the check off, and it blocks entering the waiting stage until you re-enable it.
• It’s read-only, always. CodeHerder only asks the host whether the merge request is open, merged, or closed. It never opens, merges, or writes to anything.

An integration by itself doesn’t open or land anything. Opening and landing a merge request is done by the git-host command-line tool (gh for GitHub, glab for GitLab) running on the device, signed in separately there — see Connecting repositories for that setup. Connecting an integration also doesn’t register a repository for agents to work in; that’s a separate step that doesn’t require or use an integration either.

Slack and PagerDuty

Connecting Slack or PagerDuty stores the credential and marks the connection Connected, but CodeHerder doesn’t send Slack messages or raise PagerDuty alerts from it today. If you want CodeHerder to notify you or your tools about workspace activity, use Webhooks for a signed payload sent to your own endpoint, or Watching tasks and notifications to get notified inside CodeHerder itself.

Connecting a provider

There are two ways to connect a provider, depending on which one you pick.

Credential form (GitHub, GitLab, PagerDuty)

Click a provider’s card, fill in its connection form, and click Connect:

• GitHub — a personal access token and a host. The token can be a classic token, a fine-grained token, or a legacy 40-character hexadecimal token. Enter the host as a bare hostname with no https://, port, or path: github.com, or your GitHub Enterprise Server hostname. A label and an organization are optional.
• GitLab — a personal access token with API scope, starting with glpat-, and a host in the same bare-hostname form: gitlab.com, or your self-hosted GitLab hostname. A group or namespace is optional.
• PagerDuty — an Events API v2 routing key, a severity picked from the list (critical, error, warning, or info; the form won’t save until you pick one), and whether to deduplicate alerts that share a routing key.

Every form has one secret field — the token or routing key — entered as a password field so it’s never shown on screen.

Connect with OAuth (Slack)

Click the Slack card, then Connect with Slack. You’re redirected to Slack to authorize the connection, then brought back to CodeHerder with the connection marked Connected. If authorization fails instead, you land back on the Integrations page with a “Connection failed” notice. The default channel field on this screen doesn’t carry through, so set it afterward from the connection’s own page; it must start with #.

Inherited connections

If your workspace sits under a group, any connection the group owns is available to your workspace too. Its card shows Connected plus an Inherited badge. You can’t edit or remove it here. Only the group that owns it can. Want your own connection instead? Click Configure override; creating one for that provider makes it win over the inherited one from then on. If a workspace is nested several levels deep, the nearest ancestor’s connection wins.

See Managing workspaces and Core concepts for how group nesting and inheritance work more generally.

Testing a connection

GitLab connections have a Test connection button that checks the stored token against GitLab and reports back the identity it resolves to (for example, “authenticated as @yourname”). Other provider kinds don’t support a connection test today.

Editing, disabling, and removing a connection

Open a connected provider’s card to edit its configuration. Editing a secret field always starts blank — leave it blank to keep the current value, or enter a new one to replace it.

Each connection has an Enabled/Disabled badge and toggle on the connection’s own page. The catalog card itself still reads Connected either way, so check the connection’s page to see whether it’s enabled. Disabling a GitHub or GitLab connection stops its merge-status check from running, and it blocks entering a workflow stage that waits on it until you re-enable it.

To remove a connection entirely, click Remove (or Disconnect for an OAuth-based connection like Slack) and confirm — this deletes the connection and can’t be undone. To connect that provider again afterward, you’ll need to go through the connect flow from scratch.

Security

Every secret you enter — a token or routing key — is stored encrypted. CodeHerder never displays a stored secret back to you or anyone else in the workspace, in the web app or through the API; the connection’s detail view only ever shows whether a secret is set.

Related guides

• Secrets — the workspace-level credential store agents use at runtime; a different feature from integrations, which connect the workspace itself to outside services.
• Webhooks — receive a signed payload when workspace events happen, if you need CodeHerder to push data out rather than connecting to a provider’s own API.
• Connecting repositories — register a git repository for agents to work in, and set up the device-side CLI that opens and lands merge requests.
• Reviewing an agent’s work — where a task’s merge-request link comes from, and how it’s used at the review and merge checkpoints.