# Integrations Source: https://codeherder.com/docs/integrations/ How to connect, test, disable, and remove your workspace's external 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](https://codeherder.com/docs/integrations/#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](https://codeherder.com/docs/integrations/#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](https://codeherder.com/docs/integrations/#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](https://codeherder.com/docs/task-types/)). 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 `), 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](https://codeherder.com/docs/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](https://codeherder.com/docs/webhooks/) for a signed payload sent to your own endpoint, or [Watching tasks and notifications](https://codeherder.com/docs/watching/) 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](https://codeherder.com/docs/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](https://codeherder.com/docs/workspaces/) and [Core concepts](https://codeherder.com/docs/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](https://codeherder.com/docs/secrets/) — the workspace-level credential store agents use at runtime; a different feature from integrations, which connect the workspace itself to outside services. - [Webhooks](https://codeherder.com/docs/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](https://codeherder.com/docs/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](https://codeherder.com/docs/reviewing-work/) — where a task’s merge-request link comes from, and how it’s used at the review and merge checkpoints.