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.

An unconnected provider’s card carries an Available badge and a Configure button. Once you’ve connected it, the card switches to a Connected badge. A connected GitHub or GitLab card also changes its title — see Naming a connection.

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 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 workflow to add a stage that waits on an external merge (see Customising 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 <taskId> <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. Either way, the form tells you what happens when you connect and what to do next, and each credential field names the permission it needs, where to create it, and links to a Setup guide for that provider.

Credential form (GitHub, GitLab, PagerDuty)

Click Configure on a provider’s card, fill in its connection form, and click Connect (for example, Connect GitHub):

• GitHub — a host, an organization or user, and a personal access token. The token can be a classic token, a fine-grained token, or a legacy 40-character hexadecimal token; use a fine-grained token with read-only Contents, Pull requests and Metadata permissions. Enter the host as a bare hostname with no https://, port, or path: github.com, or your GitHub Enterprise Server hostname. Host and organization are both optional; token is required.
• GitLab — a host, a group or namespace, and a personal access token with the read_api scope, starting with glpat-. Enter the host in the same bare-hostname form: gitlab.com, or your self-hosted GitLab hostname. Host and group are both optional; token is required.
• PagerDuty — an Events API v2 routing key, a severity (critical, error, warning, or info; it starts pre-filled with error), and whether to deduplicate alerts that share a routing key.

The GitHub and GitLab tokens are for reads only: merge state, conflict state, commit and merge-request lists, and Test connection. Agents open and land merge requests through the device’s own gh or glab sign-in (see Repositories). Do not give the integration token write scope. If your GitHub Enterprise Server cannot issue fine-grained tokens, a classic token needs repo, which also grants write. Use that only as a fallback.

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 Configure on the Slack card, then Connect 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 #.

Naming a connection

Once you connect GitHub or GitLab, its catalog card is titled after the connection itself, not just the provider: the host and organization (or group) you entered, for example “GitHub — acme-inc at github.example.com”. A host you leave at its pre-filled default doesn’t appear in the name, so an organization of acme-inc on the default host reads as “GitHub — acme-inc”. Leave both boxes at their defaults and the card falls back to the plain provider name. Slack and PagerDuty cards always show the plain provider name, since they don’t have a host or organization to name themselves after.

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

GitHub and GitLab connections both have a Test connection button that checks the stored token against the provider 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.