Code-Host Workflow Without Long-Lived Tokens
Updated
IntermediateWhat you'll learn
~25 min- Decide, with your agency, which code host you use, and record the decision with its date
- Open a pull request from the command line signed in through a credential helper (a tool that signs you in through your identity provider and holds a short-lived token), not a stored password or token
- Let CI reach the cloud with workload identity federation (the CI job proves who it is with a short-lived signed token that the cloud was told to trust, so no key is stored), and write the trust condition narrowly
- Name the one fact per host that changes the setup: owner approval, token subject format, issuer reachability, or a manual step
Two identities, no secret to rotate
This lesson is about two identities: the person pushing a branch and the CI job that builds it. Both can authenticate without a password or key that someone has to rotate, copy, or leak. The pattern is the same on every host:
- People sign in through a credential helper and open a pull request (PR, the review gate before code merges) from the CLI.
- CI gets a short-lived signed token from the host, presents it to the cloud, and the cloud exchanges it for a short-lived credential. The cloud holds only a trust rule, never a key.
The per-host commands and the cloud-side trust setup are in Lesson 37, Code Host and Pipeline (GitHub, GitLab, Azure DevOps and Bitbucket, each with its sign-in, PR command and federation setup). This lesson teaches what stays the same and the facts that differ.
The host is an agency decision
Which host your work lives on is not yours to pick: the agency’s authorization boundary decides it. This lesson holds no authorization claim for any host, because those facts change and are not uniformly published; ask your ISSO (the security officer who signs off on your system’s controls) and write the answer into docs/adr/ with its date.
| Host | How code-owner review is required | The fact that changes CI federation |
|---|---|---|
| GitHub | A CODEOWNERS file, plus “Require review from Code Owners” inside a branch protection rule | For repositories created after 2026-07-15 the token’s sub (subject) claim has a new immutable default format; re-check every trust condition that matches on sub. The page says that format is not available on GitHub Enterprise Server |
| GitLab | A CODEOWNERS file, plus “Required approval from code owners” on a protected branch | The issuer is your GitLab instance’s address and must be publicly reachable, so a self-managed instance behind the agency firewall cannot federate to a cloud trust without exposing its discovery and key URLs |
| Azure DevOps | No CODEOWNERS file in the documentation read; the equivalent is the “Automatically included reviewers” branch policy | Federation to Azure Government is a manual setup, because the automatic option is not offered there |
| Bitbucket | A .bitbucket/CODEOWNERS file suggests reviewers, but no native “require code-owner approval” setting was found; the closest is default reviewers plus a minimum number of approvals | A step with oidc: true receives the token; the provider path differs from the other three |
Sources for every cell are in the status box at the end of the lesson. The rest of the lesson uses neutral names (“the host CLI”, “the trust rule”); Lesson 37 turns each into the real command.
AI tools default to one host’s spelling: a particular PR command, a particular workflow folder, origin/main. Put the host, the default branch name, and the PR command in your project-memory file so the tool stops guessing.
People: a credential helper, never a stored secret
A credential helper signs you in with your organization’s identity in a browser and keeps a short-lived token. Lesson 0 installed one. A prompt that will not go away is a configuration problem with the helper; the fix is never to cache a password.
Two things to remove if a previous setup left them:
# Stores credentials in plain text in ~/.git-credentials. Remove it.git config --global --unset credential.helperrm -f ~/.git-credentials# then re-run the helper setup from Lesson 0Do not set GIT_HTTP_NO_NTLM=1 as a fix for a proxy that blocks sign-in. It hides the real failure. Take the proxy’s name and the exact error to your network team.
Feature branches and pull requests
Work happens on a short-lived branch off your integration branch, shown here as develop. The PR is the review gate: no direct pushes to develop or the release branch, and branch rules require review and a passing pipeline. Your agency may call the branches something else; keep the shape.
Plan the change with your agent
Open your workspace agent at the project root, switch to Plan mode (Shift+Tab, /plan, or the desktop app’s mode picker), and ask:
Read our project-memory file for the code host CLI and branch rules, and plan the commands to push a feature/fleet-export branch and open a pull request into develop.What to check in the plan before you approve
- Uses the configured Git credential helper and never creates, caches, or passes a personal access token on a command line or in a file.
- Creates
feature/fleet-exportoffdevelop, commits staged changes, and pushes with-u origin feature/fleet-export. - Checks the host CLI’s
pr create(or merge-request)--helpoutput first to verify the exact flags for targetingdevelopand deleting the source branch on merge.
If the agent offers to generate or cache a personal access token instead of using the credential helper, push back:
Check the host CLI's --help output for the exact branch flags, and never use a personal access token.What you get
The git half is identical on every host:
git switch -c feature/fleet-export developgit commit -m "Add fleet export route"git push -u origin feature/fleet-exportThe PR half is the host CLI’s pr create (or merge request create) command; Lesson 37 gives the four spellings. In every case the CLI reuses the sign-in you already completed, and in every case the PR cannot merge until the branch rules pass.
Branch rules are where the host differences matter most. The reviewer set, the required status checks and the code-owner approval are settings on the host, not files in your repository, so write them down in docs/adr/ as well. On Bitbucket, where no native required code-owner approval was found, say plainly that code-owner review is advisory unless an added merge check enforces it.
See it in action
- Typed in the terminal:
claude - Mode:Plan mode
- You type in the session: Push my fleet-export work and open a PR into develop.
- The tool replies: First I checked how this repo authenticates: $ git config --get credential.helper manager A credential helper that signs in through the browser, so no stored password. I will not use a personal access token. $ git switch -c feature/fleet-export develop $ git push -u origin feature/fleet-export branch 'feature/fleet-export' set up to track 'origin/feature/fleet-export'. The project-memory file names the host CLI. Next I will check that its PR create command has the flags I plan to use.
- You type in the session: Go ahead.
- The tool replies: $ <host-cli> pr create --help | grep -E 'source|target|delete' --source-branch --target-branch --delete-source-branch $ <host-cli> pr create --source-branch feature/fleet-export --target-branch develop --title "Add fleet export route" --description "Adds GET /api/fleet/export. Tested: npm test, axe pass." --delete-source-branch Pull request 142 created. Branch rules: 1 reviewer required, pipeline pending. The PR cannot merge until a reviewer approves and the pipeline passes. I did not bypass either.
- You type in the session: The push asked me for a password. Can you just create a token and cache it?
- The tool replies: I would rather fix the prompt than cache a credential. A cached token is a long-lived secret on disk. Let me check the usual causes: the helper missing on the Windows side of WSL, the helper pointing at the wrong path, or an older helper winning. $ git config --get-all credential.helper store There it is: an old 'store' helper is intercepting the request and replaying a stale saved credential. I will remove it and re-run the helper setup, then retry the push.
- You type in the session: CI fails to get a cloud credential: 'no matching federated credential'.
- The tool replies: That is the trust rule not matching the token the job presented. I will not add a stored key to get past it. Reading the job's token claims in the log (issuer, subject, audience, with no secret in them): issuer: matches the trust rule subject: the job's subject differs from the one the rule expects The repository was created recently, and the host changed the default subject format for new repositories, so a rule written for the old format no longer matches. I will print the subject from the job, update the trust rule to that exact value, and keep it limited to this repository and the deploy environment. I will not widen it to a wildcard.
Illustrative session; exact output varies by tool and agency configuration.
Pipelines: workload identity federation
A pipeline that deploys needs to prove who it is to the cloud. The old way is a service account key or client secret stored in the pipeline: a long-lived credential that expires at the worst time and leaks through logs. The pattern here is workload identity federation (using the host’s short-lived signed token as the pipeline’s identity):
- The CI job asks its host for a token. The token names an issuer (the host), a subject (which repository, branch or environment the job runs for) and an audience (who the token is meant for).
- The cloud has a trust rule that says: tokens from this issuer, with this subject and this audience, may act as this identity.
- The cloud exchanges the token for a short-lived credential scoped to that identity’s roles. Nothing secret is stored anywhere.
The cloud half of step 2 and 3 lives in your platform lesson: 34, Azure Government (federated credential on an app registration or managed identity), 35, AWS GovCloud and 36, Google Cloud with Assured Workloads. The host half is in Lesson 37.
Facts that differ, from the table above and worth stating again at the point of use:
- GitHub. The job needs
id-token: writepermission to receive a token. The defaultsubformat changed for repositories created after 2026-07-15 and is not available on GitHub Enterprise Server. - GitLab. The job declares
id_tokens:with anaud:value. The cloud must be able to reach the issuer address, so a self-managed instance behind a firewall cannot be the trust anchor for a public cloud endpoint. - Azure DevOps. A service connection set up for workload identity federation. For Azure Government the setup is manual (you create the federated credential on the cloud side yourself, with an explicit issuer and subject; the exact subject string was not verified for this lesson).
- Bitbucket. A step with
oidc: trueexposes the token inBITBUCKET_STEP_OIDC_TOKEN. The audience is the client ID the cloud’s identity provider issued for your app.
Scope the identity narrowly on every host: one environment, one role set, one trust rule per environment, and a subject that names the repository and the deploy environment instead of a wildcard.
Personal access tokens: constrained legacy
A personal access token (PAT) is a long-lived password that acts as you. Use one only when a legacy tool forces it, and then make it as narrow as the tool allows: the smallest scope, the shortest expiry, scoped to one organization or project where the host supports it, and kept out of shell history, .env files and pipeline variables stored in plain text. Check your host’s current retirement dates for token types you still depend on; this lesson does not carry them, because they change.
Prove it
Three checks, each with a pass and a fail:
# 1. No stored password helper remains. Pass: prints nothing or only "manager".git config --get-all credential.helper
# 2. No token lives in the environment or your shell history. Pass: both print nothing.env | grep -i -E '(_PAT|_TOKEN)=' | grep -v -E 'GITHUB_TOKEN=\$\{\{' || truegrep -n -E '(_PAT|_TOKEN)=' ~/.bash_history | head -1 || true
# 3. No stored cloud key or Basic credential in tracked files or CI config. Pass: prints "clean".git grep -n -i -E 'AWS_SECRET_ACCESS_KEY|AZURE_CLIENT_SECRET|GOOGLE_APPLICATION_CREDENTIALS|Authorization: *Basic' -- . ':!docs' || echo "clean"Fail on purpose once: add export EXAMPLE_PAT=x to a scratch shell and rerun check 2; it should print the variable name.
Availability, authorization, agency approval, region support, and price are five separate facts. This box holds the sourced facts for this lesson; none of it is an authorization claim.
- GitHub:
CODEOWNERSlocations and “Require review from Code Owners” (code owners); OIDC issuer,subexample andid-token: write(OIDC concepts, OIDC in cloud providers); the immutable default subject format for repositories created after July 15, 2026, not available on GitHub Enterprise Server (same OIDC concepts page). - GitLab: “Required approval from code owners” on a protected branch (code owners);
id_tokens:withaud:(ID token authentication); the OIDC provider address must be publicly accessible (AWS guide). The consequence for a self-managed instance is this module’s inference from that requirement. - Azure DevOps: the “Automatically included reviewers” policy (branch policies overview); workload identity federation service connections, and the manual path for Azure US Government (connect to Azure, configure workload identity).
- Bitbucket:
.bitbucket/CODEOWNERS(code owners); the merge-check page lists minimum approvals and default-reviewer approvals and not code owners (merge checks), so “no native required code-owner approval” is this module’s reading of that page, not an Atlassian statement;oidc: trueandBITBUCKET_STEP_OIDC_TOKEN(deploy with OIDC). - Not verified for any host in this lesson: vendor FedRAMP statements for the hosted services, and whether federation is fully supported inside each government cloud boundary.
Recheck the cited source and your agency’s authorization boundary before you rely on any of it.
A pipeline deploys to a government cloud. Which credential setup is the pattern this lesson teaches?
Your AI tool suggests running git config credential.helper store so you stop being prompted. What is the better move?
Your agency runs a self-managed GitLab instance behind its firewall, and the cloud trust rule cannot fetch the instance's discovery and key URLs. What does that tell you?
Key takeaway
Confirm the code host with your agency and write the decision down. People sign in through a credential helper and open pull requests from the CLI; pipelines authenticate through workload identity federation, with a trust rule written to one repository and environment. Each host changes one thing you must know: owner-approval enforcement, the subject format, issuer reachability, or a manual step for Azure Government. A personal access token is a constrained legacy path. Lesson 37 holds the commands for all four hosts.
- LEADERSHIP DECISION
- Which code host the agency uses, and that pipelines authenticate by trust rule rather than a stored token.
- PRACTITIONER ACTION
- Write the host decision down, then scope the trust rule to one repository and environment.
- SUCCESS MEASURE
- Audit finding avoided: no long-lived personal access token remains in a pipeline's settings.
Legend: LEADERSHIP DECISION = what a leader decides · PRACTITIONER ACTION = what the engineer does next · SUCCESS MEASURE = how you know, in calendar time, assessor-hours or cost, contract or revenue risk, or audit finding avoided