CodeHerderSearch⌘KRequest access →

Git credentials on a device

See how an agent gets git access on a device, from a server-minted token, a device key or the git-token pool, and set up each one.

An agent never holds your git login. When a session needs to fetch or push, the device hands its git a credential for that one sandbox. The device takes the credential from a token that the server mints first, then from a key on the device, then from its git-token pool. A device needs no App key and no mint token file: the server mints for the workspace that the sandbox belongs to. This page explains the order and shows how to set up each source.

The pool commands here are device-local. They talk to the ch device-server process on your machine, not to CodeHerder’s API. Run them on the device itself, with its device server already running. With no device server running, a write prints a clear message, exits non-zero, and changes nothing.

How an agent gets git access

  • Listed repositories only. The device answers only for repositories the task’s sandbox lists. Any other path gets nothing.
  • github.com and gitlab.com only. Agents get git credentials only for repositories on github.com or gitlab.com. A repository on any other host, such as a self-hosted server, gets no credential for agent git. A minted token and the pool both follow this rule.
  • Never in the session. The token does not enter the agent’s environment. The device supplies it to git when git asks. GH_TOKEN, GITHUB_TOKEN and GITLAB_TOKEN are removed from the session.
  • Read and write. A stage that can commit and a repository registered with read-write access get a write credential. A read-only stage never gets a write credential. A repository registered as read-only never gets one either, whatever the stage.
  • No fallback to your sign-in. Agent git never uses the device’s own gh auth login or glab auth login. See What the host sign-in still does, below.

The device needs agent isolation

By default, the device serves git credentials only when agents on it are isolated. Agent isolation means one of: a CH_AGENT_USER agent user on a host device, an isolated device (--isolation isolated) with a non-root image and network access, or a microVM runner. A device without isolation refuses any session whose sandbox lists repositories. The task then waits with the reason Devices lack agent isolation. An operator can accept the risk and waive this rule. The second page below names the setting.

See Isolating agent runs on a device and Repository work needs agent isolation for the setup and the exact modes.

Where the credential comes from

For each repository, the device tries these sources in order and uses the first that fits:

  1. A token the server mints. The device asks the server for a short-lived token for this sandbox and this repository alone. The server mints it through the GitHub App installation, or the GitLab connection, of the sandbox’s workspace. A sandbox never gets a token from another workspace, even when the device serves several. See Server-minted tokens, below.
  2. A token the device mints with its own key. This is optional, for a self-hosted device that has its own App key or GitLab mint token file. The device uses it only when the server does not cover the repository.
  3. A write token from the pool, only for a stage that can commit on a read-write repository.
  4. A read token from the pool.
  5. Nothing. The device then refuses to start the session. See When no credential fits, below.

The pool is the last source. The device uses it only when no installation or connection covers the repository. If the server could mint and did not (for example, it was unreachable), the device serves nothing and does not use the pool. The pool can hold a person’s token, and the request would then show that person.

The device page names the source for each host: server, device key or the pool. When the server did not cover a repository, it also says why.

Your git host shows the push and the request as opened by the owner of the credential the device used. With a GitHub token that the server minted, that is <slug>[bot]. With a GitLab project token that the server minted, it is the project token’s identity. With a pool token, it is the token’s owner. The commits inside carry different names. See Whose name is on a commit.

Server-minted tokens

Nothing is set on the device. Connect the workspace once, and the server mints for every device.

  • GitHub. Install the CodeHerder GitHub App on the repositories and connect the installation to the workspace. See Server-minted tokens for the permissions, the lifetime and the fallback.
  • GitLab. Add a GitLab connection to the workspace, with a token that has the api scope and the Maintainer role on the projects your agents work in. The server keeps that token. It never goes to a device. A connection whose token only has read_api cannot create project tokens, so the device then uses its pool as before. On GitLab.com, project access tokens need the Premium or Ultimate plan. On a Free namespace, GitLab refuses the create call with HTTP 400, whatever the token’s scope and role. The server counts that refusal as a failed mint, so the device serves no GitLab credential and does not use its pool. The server log names GitLab’s reason.

The connection’s Sandbox git tokens setting can be service_account. The server then creates a short-lived token of a project service account for each sandbox, on every GitLab tier, including Free. It owns one service account per project and role: a Reporter for read and social work, a Developer for write work. Merge requests and pushes show that service account as the author. The connection token needs the api scope and the Maintainer role. If GitLab refuses any step, the mint fails and the device serves no GitLab credential. It does not use its pool.

The setting can also be group_service_account. Use it when the connection token belongs to a GitLab group service account that is a Maintainer, or higher, of the group. The server then mints a short-lived token of that same account for each sandbox. It does not create a project token or a project bot. The token reaches only the sandbox’s project. It carries only the permissions of the work, as fine-grained permissions:

Work Permissions
Fetch Clone, and read the project, code, merge requests, notes, pipelines and jobs
A comment from a read-only stage Fetch, plus add notes and discussion replies
Push, and open or merge a merge request Fetch, plus push, change and merge merge requests, add notes, and run pipelines and jobs

Each token can also read its own user (GET /user). Pushes, merge requests and pipelines show the group service account. A pipeline then runs as that account, so it can read a CI include from another project of the group. A project bot cannot read it.

Before each mint, the server checks the connection token. It must belong to a service account, not a person. The account must be a Maintainer, or higher, of the project, directly or through a group. If a check fails, or GitLab refuses the token, the mint fails. The device then serves no GitLab credential and does not use its pool. The server revokes the token when the sandbox ends. The token expires after 48 hours at the latest.

The account is a Maintainer, so it can push to a branch that only Maintainers can push to. The API relay still gates each API call. It does not limit which branch a push writes.

For each sandbox and project, the server creates a GitLab project access token and revokes it when the sandbox ends. A sweeper on the server does the revoke, because the device never holds the connection token. The token expires after 48 hours at the latest. Its access depends on the work:

Work Scopes Role
Fetch read_repository Reporter
Push, and open or merge a merge request read_repository, write_repository, api Developer
A comment or review from a read-only stage api Reporter

Minting works for github.com and gitlab.com only.

Mint with a key on the device (optional)

A self-hosted device can still mint on its own. Set CH_GITHUB_APP_ID and CH_GITHUB_APP_PRIVATE_KEY_FILE for GitHub. Set CH_GITLAB_MINT_TOKEN_FILE to the path of a file that holds a GitLab token for GitLab. The token needs the api scope and the Maintainer role. The device reads the file again for each mint and never gives it to an agent. The device uses these only when the server does not cover the repository. The server’s App key mints for every installation of the App, so do not copy it to a device.

The git-token pool

The pool lets a device hold several labelled tokens, each scoped to a host, an access class, and optionally a set of repositories. Use it when neither the server nor the device mints for the repository. One device can then hold a write token for your own organization and a read-only token for a vendor’s repositories. It can also hold a GitHub token and a GitLab token side by side.

Adding a token

ch device git-token create <label> --host <host> --access <write|read> [--scope <prefix> ...] --from-file <path|->

<label> is a short name you choose — lowercase letters, digits, and hyphens. --host is the git host the token belongs to, such as github.com or gitlab.com. The pool also accepts another hostname. A token for another host serves only the device’s own fetches and clones, never agent git.

--access is write (can push and open a pull or merge request) or read (can only clone and fetch). --from-file reads the token from a file, or from standard input when you pass -. The device never accepts the token inline or as an argument. It can’t end up in your shell history or a process list.

ch device git-token create my-laptop --host github.com --access write --scope github.com/your-org --from-file ~/gh-token.txt
echo "$TOKEN" | ch device git-token create ci-reader --host github.com --access read --from-file -

The command checks the token’s format, adds it as a new, enabled entry, and prints its fingerprint — never the token itself. It does not contact the git host, so it can’t tell you whether the token works.

Scopes

--scope narrows a token to one or more repository-path prefixes, and is repeatable — up to 16 per token. Omit it and the token applies to every repository on that host. A scope matches on a whole path segment, so --scope github.com/your-org covers github.com/your-org/anything but not github.com/your-org-labs/foo. A scope can’t be empty, contain whitespace, or start or end with /.

Listing what’s added

ch device git-token list

This prints a row per entry: label, host, scopes, access, state, fingerprint, and when it was last used. The list never prints token material, and the CLI has no command to read one back. The pool is plain files on the device. On a device without isolation, an agent that runs as the same user can read them. See Isolating agent runs on a device.

Which token a repository gets

When the device picks from the pool, it chooses in this order:

  1. A disabled token is never a candidate.
  2. The token’s host must match the repository’s host.
  3. The token’s access class must match exactly what the stage needs. A read-only stage never receives a write token. A stage that pushes never receives a read-only one. There is no “write is good enough for read” shortcut.
  4. Among what is left, the token with the longest matching scope wins. A host-wide token (no --scope) is the fallback.
  5. If it is still a tie, the least recently used token wins, then alphabetically by label.

Disabling, enabling, and removing a token

ch device git-token disable <label>
ch device git-token enable <label>
ch device git-token delete <label>

Disabling keeps the entry but takes it out of selection. Use it when a token is about to expire or you are rotating it out. Deleting removes it outright.

Workflow files

A repo’s Workflow edits setting applies only to tokens minted from the GitHub App. It has no effect on a pool token. To let a pool token push changes under .github/workflows/, the token itself needs GitHub’s own permission for it: the workflow scope on a classic token, or the Workflows permission on a fine-grained one. See Letting agents change CI workflow files.

Release actions

A repo’s Release actions setting applies only to tokens that the server mints. It has no effect on a pool token. A pool token never runs a workflow or pushes a tag on behalf of this setting. See Release actions.

Limits

A device holds at most 32 tokens. create refuses a duplicate label, and refuses once the pool is full. Delete or disable an entry to make room.

When no credential fits

Before the agent starts, the device checks every repository the sandbox lists, at the access the stage needs. If one has no minted or pooled credential, the device refuses the session. The message reads “no git credential for <repo> (read or write) on this device”. CodeHerder retires that sandbox and avoids that device for the same task for 30 minutes. If every capable device refuses, the task waits with the reason No git credential for repo. See Why a task isn’t moving.

To fix it, do one of these on the device:

  • Set up a minter for the repository’s host.
  • Add a token with ch device git-token create that covers the repository. A write stage needs a write token.

The task starts again after the cool-down.

The device checks only repositories on github.com or gitlab.com. A local path is never checked. A repository on another host is not checked either, so the session starts. Its agent git gets no credential, so a fetch or push of a private repository fails during the session.

Readiness checks

The device reports three checks in its Health panel. All of them only warn. They never block work. See Managing your devices.

  • Git token minting appears when the device has a minter. It warns when the host refuses the minter’s credentials, the setup is only partly there, or minting has stopped working.
  • Repo-scoped git tokens warns for each repository the device works in that has no minter and no enabled pool entry.
  • Git tokens counts the pool’s tokens per host. It appears once the pool holds at least one.

What the host sign-in still does

Agent git does not use the device’s gh and glab sign-in. The sign-in still matters in two places:

  • The device’s own git work. The device fetches and clones for itself too. If no pool token covers the repository, it uses the host’s git credential setup, for example gh auth setup-git.
  • Opening and landing requests from a stage that runs directly on the device. A stage on an unisolated host device (no container of its own) uses the gh or glab sign-in of the account the agent runs as. An --isolation isolated stage does not. The device adds the credential for it. See Connecting repositories.

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