Repository access

Before a step runs, the worker clones or fetches the project's repository onto your machine, and after the step it pushes the result back. This page explains which git credential the worker uses for that, how to give it a credential of its own, and how to check that it can reach a repository.

Credential modes

Every worker has a credential mode. Pidgen sets it; you do not configure it on the machine.

Mode	Who has it	Where the git credential comes from
local_only	A worker you set up for your own machine.	Never from Pidgen. The worker uses a matching entry in its git_credentials table, and otherwise the machine's own git credentials, exactly as git does when you run it yourself.
platform	A shared worker enrolled for the Account as a whole rather than for one member's machine.	A matching entry in its git_credentials table, and otherwise a short-lived credential Pidgen grants for one fetch or push, from the forge connection your Account set up.

On a local_only worker the machine's own credentials are:

• a git credential helper, such as the macOS keychain helper or git credential-manager;
• ~/.git-credentials, when the store helper is configured;
• an SSH key, through the SSH agent (SSH_AUTH_SOCK) or the key files ssh finds by default, and GIT_SSH_COMMAND when you set one.

So fetches and pushes are made as you, with whatever access your account has on the forge, and your Account's forge token never reaches the machine. Commits the worker makes carry the name and email of the machine's git configuration (user.name and user.email). Pull requests are opened by Pidgen, not by the worker.

The git_credentials table

The worker policy, config/worker-policy.yaml in the worker's home, can give the worker credentials of its own for particular remotes. Each entry maps the start of a remote URL to an environment variable holding a token. The token itself is never written in the policy:

git_credentials:
  - remote_url_prefix: https://github.com/acme/
    credential: env:ACME_GITHUB_TOKEN
  - remote_url_prefix: https://gitlab.example.com/
    credential: env:EXAMPLE_GITLAB_TOKEN
    username: oauth2

Key	Meaning
remote_url_prefix	The start of the remote URLs this entry covers. It must not contain a user name or password.
credential	env:NAME, where NAME is the environment variable holding the token.
username	Optional. The user name sent with the token. Left out, it is x-access-token for GitHub and oauth2 for GitLab.

How an entry is chosen:

• The longest matching prefix wins.
• A prefix matches only up to a / or :, so https://github.com/acme covers https://github.com/acme/app.git but not https://github.com/acme-corp/app.git.
• An entry is used only when its variable is set in the worker's environment.

The shipped policy has an empty table, git_credentials: [].

Add a token

1. Create a token on your forge that can read and push to the repositories, for example a fine-grained GitHub token limited to those repositories.

2. Add it to worker.env in the worker's home, on a line of its own:

   ACME_GITHUB_TOKEN=github_pat_EXAMPLE_NOT_A_REAL_TOKEN

   worker.env holds the worker's own credential too: keep it readable only by you.

3. Add the entry that names it to git_credentials in config/worker-policy.yaml.

4. Check the policy with pidgen-worker doctor; a mistake in it is reported under worker_policy.

5. Restart the worker so that every process it runs reads the new values (see Workers in the Pidgen CLI docs).

The token is passed only to the git process that fetches or pushes. It never appears in a ticket, a workflow, an event or a log, and no coding agent receives it.

Projects that need a local credential

A project can require that its repository be reached with a credential on the worker rather than one from Pidgen. On a platform worker such a project needs a matching git_credentials entry; on a local_only worker the machine's own credentials may be enough. When neither reaches the repository, preparing its workspace fails with LOCAL_GIT_CREDENTIAL_REQUIRED. The failure names the remote, without any user name, and which credential git ran with (the entry's prefix and variable, or ambient for the machine's own), never the token. Add an entry, or give the machine access to the forge, and the next attempt succeeds.

What the worker reports to Pidgen

The worker tells Pidgen which of its projects it can reach, so that work goes to a worker that can fetch it. It never sends a credential.

• A platform worker reports which projects a git_credentials entry covers, when it starts and whenever the policy changes.
• A local_only worker checks each project's remote by running git ls-remote with the credential git would use, and reports whether that worked. It checks every five minutes, and within seconds after a fetch failed with LOCAL_GIT_CREDENTIAL_REQUIRED, so the report follows a fix just as fast.

These checks run with prompts switched off: git may not ask for a password and SSH runs in batch mode. A credential that works only when someone types a passphrase, or an SSH host key that has never been accepted, therefore fails here even though it works in your terminal. Add the forge's host key to ~/.ssh/known_hosts and use an agent-held or passphrase-free key.

Snapshot references

To record the reviewed state of a step, the worker pushes a commit to a reference under refs/pidgen/snapshots/ in the project's repository, with the same credential it uses for other pushes. The credential must be allowed to push to that namespace; if it is not, the step still completes, and the failed push is recorded with the snapshot. Do not delete these references while a reviewed change is still waiting to be delivered.

Check access by hand

Run, as the operating-system user the worker runs as:

GIT_TERMINAL_PROMPT=0 git ls-remote https://github.com/acme/app.git HEAD

It should print one line with a commit id and HEAD. If it asks for anything or fails, the worker cannot reach that repository either. For an SSH remote, ssh -T git@github.com shows whether your key is accepted.