CodeHerderSearch⌘KRequest access →

Integrations

How to connect, test, disable, and disconnect your workspace's external integrations. Also agent access and personal accounts.

Integrations connect your workspace to external services like GitHub, GitLab and Jira. Slack posts task events to your channels. 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. You manage integrations in the web app. There is no ch command to connect or edit one. The one read-only command is ch jira status (see Jira).

Who can manage integrations

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

The provider list

The Integrations page lists the providers you can connect. Each provider is a card with its name, a badge and a one-line summary. Click a card to open that provider’s page. Today, three providers connect with a credential:

  • GitHub — connect to a GitHub host or organization with a personal access token. You need the token only for repos the GitHub App does not cover.
  • GitLab — connect to a GitLab host or group with a personal access token.
  • Jira — connect a Jira Cloud site with the email and API token of a service account.

Slack connects with OAuth instead. See Connect with OAuth (Slack). CodeHerder adds more providers over time. Check the list to see what is available.

The page also shows a Claude card. It has no connection to make. It holds the requests to approve the Claude settings your organization serves. See Approving your organization’s Claude settings.

The badge on a card tells you where the provider stands:

  • Not connected — the workspace has no connection to this provider and inherits none.
  • Connected — the workspace has a connection, its own or one from a group. An inherited one also carries an Inherited flag. See Inherited connections.
  • Coming soon — you cannot connect this provider yet. Its page says so.

The summary line says more. See Naming a connection.

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.

The provider page

A provider’s page opens when you click its card. The header shows the provider’s name, a short description and the same badge. Below it, a Connection panel shows:

  • Inherited from — a link to the group that owns the connection, when it is inherited.
  • The values you entered, such as the host or the site. The token is never shown. The panel only says Stored.
  • State — Enabled or Disabled.
  • Who made the connection and when.

With no connection, the panel reads “Not connected.” Owners and admins also see the actions for the connection here: Connect, Edit connection, Disconnect, Test connection, or Configure override. Which ones appear depends on whether the connection is your own, inherited, or missing.

The page of a provider with agent access (Jira, Datadog) also has an Agent access panel and, for Jira, a Your account panel. See Agent access and Your account.

Some providers add panels to their page:

Agent access

Agent access lets an agent use a connected service such as Datadog or Jira. The credential stays on the CodeHerder server. The agent never holds the vendor key. Only Jira and Datadog have agent access today.

Turn on agent access

  1. Add the main connection for the service on the Integrations page. It acts as a service account.
  2. Open Admin → Integrations, and choose the service. In Agent access, turn it on. Or run ch integration enable <kind>.
  3. Start a stage. The agent calls the vendor tool as normal. For Datadog, the tool is pup.

Only a human admin can change an agent-access setting. A group setting applies to its workspaces. The nearest setting wins, so a workspace can set its own row. Run ch integration reset <kind> to return to the inherited value.

Choose a write policy

A read call always runs. For a write call, choose a policy. Run ch integration set <kind> --write-policy ask|allow.

  • ask is the default. A person must approve each write first.
  • allow runs a write at once.

A destructive tool is never listed and cannot run. A tool or route with no class is treated the same way. The policy applies to Jira tools and to Datadog write routes.

Write rules

A write policy covers every write of a service. A write rule narrows that for one tool, one target, or one stage of a workflow. A rule has three parts:

  • Op. One write tool (for Jira, a tool name such as jira_create_issue), or any write.
  • Target. A Jira project key, a Datadog site, or any target.
  • Decision. Allow runs the write at once. Ask first waits for a person. Deny refuses it.

With no matching rule, the write policy applies. A rule never changes a read. It never allows a tool that the service page does not list.

To manage rules, open Admin → Integrations, choose the service, and find Write rules in Agent access. The table shows the op, target, where the rule applies, the decision and the source. A human admin or owner adds rules with New rule and changes or deletes them. Other members can read the table. A rule on a group applies to its workspaces. The table marks it as inherited, and you change it on the group.

Limit a rule to one stage. Choose a Workflow and a Stage. The rule then applies only to calls from a task of that workflow while the task is in that stage. Stages come from your own workflows, so CodeHerder has no built-in stage names. CodeHerder reads the stage from the task, and an agent cannot claim one. A call with no stage, such as a session with no task, matches only rules that apply in any stage. The same holds if the task has left the stage the session started for.

Deny one Jira issue. Enter a Jira issue key in a rule. The decision is then always Deny. The rule refuses every write call that touches that issue, including a comment, a transition, and either end of a link. It beats every allow, including an approval and “Always allow this tool for this target”. You can limit it to a stage too.

Which rule wins. An issue deny always wins. Otherwise CodeHerder picks the most specific rule:

  1. A rule that names both the op and the target, then one that names only the op, then only the target, then neither.
  2. For a tie, a rule that names a workflow and a stage, then a stage, then a workflow, then neither.
  3. For a tie, the rule from the nearest workspace.

To work with rules from the CLI:

ch integration policy list jira
ch integration policy set jira jira_create_issue --target EZ --decision allow
ch integration policy set jira jira_transition_issue --target EZ --stage <stage> --decision allow
ch integration policy set jira jira_transition_issue --issue EZ-7 --decision deny
ch integration policy check jira jira_transition_issue --target EZ
ch integration policy delete jira <ruleId>

set and delete need a human admin. A session credential cannot run them. set takes --workflow to name a workflow, and with --stage it must name a stage of that workflow. Setting a rule for the same op, target and scope changes its decision. list shows the rule ids for delete.

check shows what CodeHerder decides for an op on a target, and which rule decides. Any member, an agent included, can run it before a call. Add --task <taskId> to see the answer for that task’s current stage.

Approve a write

With ask, the first write call is refused. CodeHerder files a question with the header “Integration write”. The question names the rule that applied, or says that the connection default is ask. The options are “Approve once”, “Always allow this tool for this target” and “Deny”. The task waits like it does for any question.

  • A person signed in outside a session can answer. This is the agent’s operator, or a workspace admin or owner.
  • “Always allow this tool for this target” approves the call. When a human admin of the workspace picks it, CodeHerder also adds an allow rule for that tool and target. A call with no target shows “Always allow this tool”, and the rule then covers every target (*). When a person who is not an admin picks it, the call runs once and no rule is added.
  • Any other answer denies the call.
  • An approval works once. It expires after 24 hours.
  • An approval binds to the identity and the arguments. A changed argument or identity asks again.

After you approve, the agent repeats the same call.

Allow personal accounts

Turn on the personal account control in Agent access, on the service page in Admin → Integrations. Or run ch integration set <kind> --override-allowed true. A task then acts as the person who filed it, if that person connected an account. Else it uses the main connection. Today only Jira takes a personal account. If you turn the control off, the accounts stay stored but go dormant.

Review integration calls

Run ch integration calls. Narrow it with --kind, --task or --outcome allowed|asked|approved|denied|refused|error. The Integration calls panel in Agent access, on the service page in Admin → Integrations, shows the same rows.

Each row shows the time, kind, operation, target, class, outcome, identity, status, latency, task and question. The Rule column shows the rule that decided. The panel shows Default when no rule did. When the call came from a task stage, it also shows the workflow and stage. CodeHerder keeps rows for 90 days. It stores a hash of the arguments, never the arguments.

A self-host admin sets the server knobs first. See Set up vendor integrations.

Move from Datadog secret variables

An older route stored DD_API_KEY, DD_APP_KEY and DD_APPLICATION_KEY as secret variables. Agent access, on the Datadog page in Admin → Integrations, shows a notice while any of them remain and agent access for Datadog is on. CodeHerder does not delete them for you.

  1. Add a Datadog main connection on the Integrations page.
  2. Turn on agent access for Datadog.
  3. Run pup logs search in a stage. Check that it works.
  4. Delete the DD_API_KEY, DD_APP_KEY and DD_APPLICATION_KEY secret variables.

While agent access is on, a stage ignores those variables. The stage uses the relay instead. If you turn agent access off, the variables work again until you delete them.

Your account

A member can connect a personal account. This applies when an admin allows personal accounts.

Connect your account

Open Your account on the Jira page in Admin → Integrations. The user menu links there. Pick the Jira site. Then give an API token with your Jira account email. Or choose “Sign in with Atlassian” when your operator set it up. An admin must connect the Jira site first.

From a terminal, run ch integration connect jira --site <url> --email <email> --from-file <path>. Use - as the path to read the token from stdin. Never put the token in the command.

When a task acts as you

A task acts as you only when all of these are true:

  • The workspace allows personal accounts for the integration.
  • You filed the task, or the task started from one you filed. In a dev session, the person is you.
  • You are an active member of the workspace.
  • Your connected account is active.

Else the task uses the main connection. The Usable in column lists the workspaces where your account works. A dormant account is active, but no workspace allows it.

A Jira comment made with the main connection does not sync back to the task. A comment made as you does.

Disconnect, or leave

Select Disconnect on the row. Or run ch integration disconnect <grantId|kind>. A disconnected row stays listed for 30 days.

When you leave the account, CodeHerder revokes every connected account in it. Where the vendor supports it, it revokes them at the vendor too. When you leave one workspace, your account stays. That workspace uses the main connection.

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 for merge checks 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 way to read the repo and a recorded merge-request link are both required to enter it. On GitHub, a GitHub App installation that covers the repo is enough. A personal access token is needed only for repos the App does not cover. Without a way to read the repo, or without a merge-request link recorded on the task (ch task merge-requests create <taskId> <pr-or-mr-url>, or a pull request link written into the task’s artifact field), 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.
  • The merge check is read-only. For this check, CodeHerder only asks the host whether the merge request is open, merged, or closed. It never opens, merges, or writes to anything.

A GitLab connection with the api scope and the Maintainer role has a second use: the server uses it to mint a short-lived project token for each sandbox, so the agent’s push and merge request show the project token’s identity and not a person’s. A GitHub App installation does the same for GitHub. The token stays on the server and only the minted token goes to the device. See Git credentials on a device. The connection 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, with the minted token or a token the device holds — 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.

Jira

A Jira connection links your Jira Cloud site to CodeHerder. A Jira issue that enters a status you choose creates a task. Comments sync both ways. A stage change moves the Jira issue. See Setting up Jira for the full steps.

  • Jira Cloud only. A Jira Data Center or other self-managed site is refused.
  • Check on connect. CodeHerder asks Jira to confirm the email and token. If Jira refuses them, or the address is not a Jira Cloud site, nothing is saved and the form shows the reason.
  • Webhook address. ch jira status shows a webhook URL. Add it in Jira with the webhook secret. See Setting up Jira.
  • Inheritance. A workspace uses its own connection, or the nearest group’s. See Inherited connections.

To see what a workspace uses, run ch jira status. Use --workspace <ref> to name another workspace, or set CH_WORKSPACE_ID. Any member can run it. It prints:

  • whether a connection exists and whether it is enabled
  • the site address, the service account, and its email
  • the workspace that owns the connection, marked (inherited) when it comes from a group
  • when the connection was made
  • a disabled reason and a fix, when the connection is off

It never prints the API token. With no connection, it prints connected: no.

Pull request and merge request discussion

When a task is linked to a pull request or merge request, the discussion on it appears as comments on the task. This covers a plain comment, a review comment on a line of code, and a review summary, on GitHub and GitLab. A comment shows a source badge, the host login of its author, the request (for example group/core!3130), the file and line when there is one, and a link to the thread on the host. A task with requests in two repos shows both, each labeled by its own repo.

  • Who wrote it. If a workspace admin has verified the host login of a member (see ch member host-login), that member is the author. Otherwise a placeholder named Git host is the author. The host login always shows beside it.
  • Edits and deletes. An edit on the host updates the comment and keeps the earlier text as a revision. A delete on GitHub leaves a note that the comment was deleted. GitLab does not tell CodeHerder about a deleted note, so a deleted GitLab note stays until a later refresh.
  • Waking the agent. A new comment is a task.commented event like any other, so it wakes the task’s live agent.
  • Quiet the bots. A workspace admin can drop or fold the comments of a host login, such as dependabot[bot]: ch workspace host-bot-rules create dependabot[bot] --mode collapse. A dropped comment never appears. A folded comment shows as one line that you can open. The rule applies to the workspace and everything below it. CodeHerder’s own identity is always dropped. An admin can also add and remove rules in the Bot comments panel. Open Admin → Integrations, then GitHub. Inherited rules and the built-in CodeHerder rule show there as read-only.

Host comments are text from outside CodeHerder. Agents read them as untrusted data, not as instructions.

Posting a task comment to the pull or merge request

A task comment can also go to the pull or merge request. This is off by default. A workspace admin turns it on in Settings → General → Post task comments to the pull or merge request, or with ch workspace edit --host-comment-writeback true.

  • You choose each comment. CodeHerder never posts a comment on its own. Tick Also post to PR/MR in the comment box, or run ch task comment <id> --to-host. A comment you do not mark stays in CodeHerder.
  • Pick the request when there are several. A task with more than one pull or merge request needs your choice: use the picker, or --pr <url>. CodeHerder never posts one comment to every request.
  • Reply in a thread. Choose Reply on host on a mirrored comment, or use --reply-to <commentId>. On GitLab the reply lands in the same discussion. On GitHub a reply to a line comment lands in the same thread. GitHub has no reply for a plain comment or a review summary, so the reply goes in the pull request conversation.
  • Who the host sees. The GitHub App posts on GitHub. On GitLab, the connection token posts. Use a project or group access token for the connection, so the comment carries a bot name. The comment starts with your name, so readers know who wrote it. CodeHerder never uses a member’s own token.
  • No echo. The comment does not come back as a second task comment.
  • A failure shows on the comment. The comment in CodeHerder is always saved. If the host refuses the post, the comment shows the reason and a Retry button (ch task comments retry). CodeHerder retries a network error or a busy host by itself, up to five times.
  • Resolve a thread. An agent can resolve the host thread that holds a mirrored comment. Run ch task comments resolve <commentId>, or reply and resolve in one step with ch task comment <id> --reply-to <commentId> --resolve. The reply posts first. A failed reply never resolves the thread. CodeHerder resolves the thread as the GitHub App or the GitLab connection, never as a member. GitHub resolves a pull request review thread. A plain pull request comment or a review summary has no thread, so CodeHerder refuses it. GitLab resolves a merge request discussion. A single note that is not part of a discussion has no thread, so CodeHerder refuses it. The comment in CodeHerder then shows a Resolved chip, and the activity log names the agent, the session and the thread. A person always resolves threads on the host. The workspace setting Agents may resolve threads limits agents only. See Whose threads an agent may resolve.
  • Later edits stay local. If you edit a comment in CodeHerder after it posts, the host copy does not change.
  • Limits. Each workspace can post 10 comments at once, then 30 per minute. CodeHerder records each post in the activity log.

The GitHub App needs the Pull requests: write and Issues: write permissions. The default App manifest has both: see Connecting the GitHub App. To resolve a review thread, the App also needs Contents: write. GitHub does not document that, but it refuses resolveReviewThread to an App without it. The default manifest has it. On GitLab, the connection token needs the Developer role on the project.

Whose threads an agent may resolve

A workspace admin sets Agents may resolve threads in Settings → General → Pull and merge requests, or with ch workspace edit <ref> --host-thread-resolve <value>. The setting applies to this workspace only. A group’s value does not reach its workspaces.

Value An agent may resolve
off (default) No thread.
bots A thread that a bot started, such as a code review bot.
bots_and_peers A thread that a bot or another agent started.
all Any thread.

CodeHerder reads the author of the first comment in the thread, from the host, at the time the agent resolves. A bot is an account the host marks as a bot, a GitLab project or group access token user, or a login with a bot rule (see Quiet the bots, above). An agent is CodeHerder’s own identity, or a person whose host login an admin linked to an agent member. Anyone else counts as a person. When the setting refuses, the error names the value that allows it. Posting to the host must be on for any resolve to work, and a person is never limited by this setting.

Slack

A Slack connection lets CodeHerder post task events to Slack channels. You add a delivery route for each channel and choose which kinds of event it gets. See Posting task events to Slack. To send a custom payload to your own endpoint, use Webhooks. To get notified inside CodeHerder, see Watching tasks and notifications.

Connecting a provider

There are two ways to connect a provider. 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, Jira)

Open the provider’s page and click Connect. Fill in the connection form, then click Connect integration:

  • 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 Contents, Pull requests and Metadata as Read-only only. 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 starting with glpat-. The read_api scope is enough to read merge state. Add the api scope and the Maintainer role if CodeHerder should also register project webhooks (see GitLab webhooks). 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.
  • Jira — a base URL, an email, and an API token. All three are required. Type the base URL in full, with https://, for example https://yourorg.atlassian.net. Use the email of a dedicated Jira service account, and name the account CodeHerder. A service account can only create scoped API tokens. Give the token the scopes read:jira-work, write:jira-work and read:jira-user. CodeHerder checks the email and token with Jira before it saves anything.

The GitHub and GitLab tokens are mainly for reads: merge state, conflict state, commit and merge-request lists, and Test connection. The one optional write is the GitLab webhook: a GitLab token with the api scope lets CodeHerder create project webhooks (see GitLab webhooks). That scope widens what a leaked token can do, so skip it if you prefer to set up hooks by hand. Agents open and land merge requests through the device’s own gh or glab sign-in (see Repositories). CodeHerder no longer posts its CodeHerder commit status, so the GitHub token needs no write permission. Give the GitHub token no write permission. 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 — entered as a password field so it’s never shown on screen.

Connect with OAuth (Slack)

Open Slack from the provider list and click Connect, then Connect integration. Slack opens. Approve the request, and you return to the Slack page with a success notice and the Connected badge. If the connection fails, you return to the Integrations page (the provider list) with an error notice. Try again. On a self-hosted server, Connect stays disabled until the operator sets up the Slack app. The page gives the reason and links to Setting up the Slack app. Then invite @CodeHerder to a channel in Slack and add a delivery route for it. See Posting task events to Slack for the full steps.

Naming a connection

A card’s title is always the provider’s name. The summary line names the connection.

  • GitHub — “Token for github.com.” names the host of the token connection. “GitHub App on 2 accounts.” counts the App installations. A card with both shows both sentences.
  • GitLab — “Connected to GitLab — acme-inc at gitlab.example.com.” names the group and host you entered. A host left at its pre-filled default is left out, so a group of acme-inc on the default host reads “Connected to GitLab — acme-inc.” With both boxes at their defaults, the line reads “Connected to GitLab.”
  • Slack — “Connected to (Slack).” names the Slack team.
  • Jira — “Connected to Jira.”
  • No connection — “Not connected.”

A turned-off connection adds “Turned off.” to the line. For GitHub, the line says “Connected, but turned off.” when no other method is active. An inherited one starts with “Inherited from” and the group’s name.

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 flag. On the provider page, Inherited from links to the group that owns it. You can’t edit or disconnect it from the workspace. Only that group can. Want your own connection instead? Click Configure override on the provider page; 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

On the provider page, GitHub, GitLab and Jira connections have a Test connection button. It checks the stored token against the provider and reports the identity it resolves to (for example, “authenticated as @yourname”). For Jira, it confirms the site and the service account. Slack has no connection test today.

If Jira refuses the stored token during a test, CodeHerder turns the connection off and tells you so. To fix it, create a new API token for the service account, then click Edit connection and enter the new token. Saving it checks the token with Jira. Then tick Enabled again on the edit page. ch jira status shows the same fix while the connection is off. A site that is not Jira Cloud, or a bad base URL, shows an error but leaves the connection on.

Editing, disabling, and disconnecting

To change a connection, open the provider’s page and click Edit connection. Editing a secret field always starts blank — leave it blank to keep the current value, or enter a new one to replace it. For Jira, a change to the base URL, email or token is checked with Jira first, and CodeHerder saves it only if Jira accepts it. Click Save changes when you finish.

The edit page has an Enabled checkbox. Clear it and save to turn the connection off. The provider page then shows Disabled in the State row. The card badge still reads Connected, and the summary line says the connection is turned off. 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 Disconnect on the provider page and confirm. This deletes the connection and can’t be undone. To connect that provider again, 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.

  • Plugins — a plugin that calls an outside service adds its own provider here, and you connect it.
  • Connecting the GitHub App — install the CodeHerder Cloud GitHub App so GitHub sends events to your workspace.
  • 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.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close