Code Host and Pipeline: GitHub, GitLab, Azure DevOps, Bitbucket
Updated
IntermediateWhat you'll learn
~60 min- Write the pipeline file for your host so it does nothing but call lesson 19's scripts/ci/ stages in order, and run the headless agent review in a job that holds no cloud identity
- Sign the release job in to your cloud with OIDC (OpenID Connect: the host hands the job a short-lived signed identity token that the cloud was told to trust), and name the one fact per host that breaks the trust rule
- Require review by the owners of referee paths (the files that decide whether work passes, from lesson 25) with your host's own mechanism, and write the compensating procedure where the host has none
- Separate what runs on your laptop (YAML parse, the owner-approval check) from what only your host can prove, and record each host check as run or NOT RUN
The pipeline file is the thin part
Lesson 19 put the logic in scripts/ci/<stage>.sh: lint, typecheck, unit, contract, build image, SBOM, scan, deploy, and a review step. This lesson writes the part that is not portable: the file your code host reads, the way its jobs prove who they are to your cloud, and the way it makes the right people review the files that judge the agent.
Before the detail — Artifact: one pipeline file for your host that calls the stage scripts in order, a cloud trust rule that names an issuer, a subject and an audience, and an owner-review setup for the referee paths. Acceptance test: the pipeline file parses on your laptop, the owner-approval check fails a planted change to a referee path and passes once an owner has approved, and every check that needs your host carries a status of run or NOT RUN. Status of what follows: reusable guidance. Which host you use is your agency’s decision, and nothing here is a federal requirement.
Four things differ by host, and the rest of this lesson is those four, side by side:
| Concern | GitHub | GitLab | Azure DevOps | Bitbucket |
|---|---|---|---|---|
| Pipeline file | .github/workflows/*.yml | .gitlab-ci.yml | azure-pipelines.yml | bitbucket-pipelines.yml |
| Owner file | CODEOWNERS in .github/, root or docs/ | CODEOWNERS in root, docs/ or .gitlab/ | none; a branch policy | .bitbucket/CODEOWNERS |
| Enforcement of owner approval | a branch protection setting | a protected-branch setting | a branch policy | none found; a compensating procedure |
| How the job gets its identity token | id-token: write permission | id_tokens: keyword | a service connection | oidc: true on the step |
Availability, authorization, agency approval, region support, and price are five separate facts. This box holds the dated host facts for this lesson; the prose does not state them. They were read from vendor documentation through a delegated fetch that returns a summary of each page, not run against a live organization, so re-check a quote against its page before you rely on it.
GitHub. Issuer https://token.actions.githubusercontent.com; a sub (subject) example is repo:octo-org/octo-repo:environment:prod: https://docs.github.com/en/actions/concepts/security/openid-connect. The job needs id-token: write: https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-cloud-providers. CHANGED: “Repositories created after July 15, 2026” get an “immutable default subject format that includes owner and repository IDs”, and the page says that format is “not available on GitHub Enterprise Server”, so re-check every trust condition that matches on sub. GHE.com issuer: “The value of iss in your OIDC token would be https://token.actions.octocorp.ghe.com” (octocorp is the example enterprise subdomain): https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/oidc. UNVERIFIED: the enterprise-slug issuer variant. GitHub Enterprise Server 3.22 issuer https://HOSTNAME/_services/token, and you “must define at least one condition”: https://docs.github.com/en/enterprise-server@3.22/actions/reference/security/oidc. Code owners: last matching pattern wins, no sections; “Require review from Code Owners” sits inside a branch protection rule, and a ruleset has the equivalent: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners. Plan gating for private repositories is UNVERIFIED; the protected-branches page names GitHub Team and GitHub Enterprise Cloud for organization-owned repositories.
GitLab. id_tokens: with aud:: https://docs.gitlab.com/ci/secrets/id_token_authentication/. The AWS guide says the provider address is “The address of your GitLab instance, such as https://gitlab.com” and must be publicly accessible: https://docs.gitlab.com/ci/cloud_services/aws/. Extended sub claim fields were introduced in GitLab 18.7. UNVERIFIED: the issuer for GitLab Dedicated for Government, and any GovCloud ARN form on that page. Code owners: “the last matching entry is used”; sections, with ^[Go] making a section optional: https://docs.gitlab.com/user/project/codeowners/reference/. “Required approval from code owners” on a protected branch is Premium and Ultimate. Protected branches exist in Free, Premium and Ultimate: https://docs.gitlab.com/user/project/repository/branches/protected/. The “Status checks must succeed” merge request setting is Ultimate: https://docs.gitlab.com/user/project/merge_requests/status_checks/. The push rule “Commit must be signed” is Premium and Ultimate: https://docs.gitlab.com/user/project/repository/push_rules/. UNVERIFIED: the “Pipelines must succeed” label.
Azure DevOps. “We recommend using workload identity federation with either an app registration or managed identity”: https://learn.microsoft.com/en-us/azure/devops/pipelines/library/connect-to-azure (ms.date 2026-08-18). The issuer https://vstoken.dev.azure.com “retires on July 1, 2027” and is replaced by https://login.microsoftonline.com/ for new public-cloud connections; “Non-public clouds and multitenant applications are excluded”, so Azure US Government connections “continue to use the Azure DevOps issuer”, and the automatic app-registration path is not for Azure US Government. The manual path is on https://learn.microsoft.com/en-us/azure/devops/pipelines/release/configure-workload-identity (ms.date 2026-08-18), with Entra credential type “Other issuer” and “Explicit subject identifier”. UNVERIFIED: the exact subject string, full support of federated service connections in the Government environment (inferred from the exclusions), and a federated credential at login.microsoftonline.us. Branch policy names, ms.date 2026-02-17: “Require a minimum number of reviewers”, “Check for comment resolution”, “Add Build Validation policies”, “Add Status Check policies”, “Automatically included reviewers”, and the bypass permissions “Bypass policies when completing pull requests” and “Bypass policies when pushing”: https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies. The plan tier of the required-reviewer policy is UNVERIFIED. Force-push and signed-commit handling are UNVERIFIED. Microsoft’s guidance, recorded in the module baseline, is that hosted Azure DevOps Services is not offered in GCC and that agencies use Azure DevOps Server, Azure DevOps Services where FedRAMP is not required, or GitHub; the GCC statement was seen in a search snippet only, so treat it as UNVERIFIED.
Bitbucket. oidc: true on a step yields BITBUCKET_STEP_OIDC_TOKEN; the provider path is oidc-provider/api.bitbucket.org/2.0/workspaces/{WORKSPACE}/pipelines-config/identity/oidc; the sub format is {REPOSITORY_UUID}[:{ENVIRONMENT_UUID}]:{STEP_UUID}; the audience is “the client ID issued by the Identity provider for your app”: https://support.atlassian.com/bitbucket-cloud/docs/deploy-on-aws-using-bitbucket-pipelines-openid-connect/. That page has no GovCloud mention, and no Pipelines OIDC page was fetched for Bitbucket Data Center. Cloud code owners: “Create the CODEOWNERS file in a directory called .bitbucket at the root of your repository”, and “The last matching pattern in the CODEOWNERS file has the highest precedence”: https://support.atlassian.com/bitbucket-cloud/docs/set-up-and-use-code-owners/. That page describes suggested reviewers only. The merge-check page lists “Minimum number of approvals” and “Minimum number of approvals from default reviewers” and does not list code owners; some settings are Premium-gated: https://support.atlassian.com/bitbucket-cloud/docs/suggest-or-require-checks-before-a-merge/. That no native owner-approval setting exists is an inference from those two pages, not a vendor statement. UNVERIFIED: Bitbucket branch restrictions (the page returned 404) and Data Center owner enforcement.
Cloud side. UNVERIFIED in the sources for this lesson: the AWS GovCloud IAM OIDC provider and Google workload identity federation on the CI side, and any trust path from GitLab, Azure DevOps or Bitbucket to a cloud other than the one named in that host’s source above.
Agent review integrations, from the agent-tool research of 2026-11-05. Claude Code: anthropics/claude-code-action@v1 for GitHub; a GitLab integration in beta, maintained by GitLab; no Azure Pipelines page seen (that negative is not exhaustively verified). Codex: openai/codex-action@v1 for GitHub; no GitLab or Azure job found. Antigravity and Copilot: no official CI integration; Copilot’s documentation says to install its CLI on the runner.
Recheck the cited source and your agency’s authorization boundary before you rely on any of it.
Plan the change with your agent
Your project memory already names the host (lesson 17). This task touches repository settings across multiple paths, so open your tool in the project root, turn on Plan mode inside the session (Shift+Tab, /plan, or the mode picker; Lesson 2’s four-tool table has the other spellings, such as Codex’s --sandbox read-only), and ask your agent to plan the pipeline and owner-review setup:
Plan the pipeline configuration and code-owner protection files for the host named in our project-memory file so every stage delegates to scripts/ci/ and only the release job requests an OIDC token. Ask me anything unclear before writing files.What to check in the plan before you approve
- Thin stage scripts only: The pipeline file only calls
scripts/ci/<stage>.shin lesson 19’s order (lint,typecheck,unit,contract, andreviewon pull requests;build-image,sbom,scan, anddeployon the integration branch), passingBASE_REF,REGISTRY,PLATFORM, andSCAN_CMDthrough the environment with no CI-dialect variable names inside the scripts. - Least-privilege job identities: The
reviewjob receives no cloud identity and no deploy variables; only thereleasejob requests a short-lived OIDC identity token, with zero stored cloud keys, personal access tokens, or registry passwords. - No invented host syntax: If the agent is uncertain whether a YAML keyword or branch-protection label exists on your host, it flags the key for you to check against the host’s documentation rather than guessing.
- Referee path ownership:
CODEOWNERS(or the host’s branch-policy equivalent, plusscripts/ci/referee-approval.shon hosts without native enforcement) covers every path inmodernization/referee-paths.txt, owned exclusively by teams and never by the agent’s account.
If the first plan grants id-token: write (or oidc: true) at the top of the workflow configuration so the review job inherits cloud credentials, correct it before approving:
Set top-level permissions to contents: read only, and grant the OIDC identity token solely on the release job so the review job has no cloud identity.Open the panel for your host. Each one covers the same five things in the same order: the pipeline file, signing in to the cloud, owners and required approval, branch protection, and the agent review step.
GitHub: the pipeline file
Three jobs. The checks job runs on every pull request and every push to the integration branch. The review job runs on pull requests only. The release job runs on pushes only, and it is the only one that holds id-token: write.
REFERENCE CONFIG .github/workflows/ci.yml: GitHub Actions workflow delegating to scripts/ci/ open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
name: cion: pull_request: branches: [develop] push: branches: [develop]permissions: contents: readjobs: checks: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version-file: .nvmrc - run: bash scripts/ci/lint.sh - run: bash scripts/ci/typecheck.sh - run: bash scripts/ci/unit.sh - run: bash scripts/ci/contract.sh review: if: github.event_name == 'pull_request' runs-on: ubuntu-latest permissions: contents: read # no id-token here: the review job has no cloud identity steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-node@v4 with: node-version-file: .nvmrc # install the agent CLI your agency approved (lesson 1) on the runner - run: bash scripts/ci/review.sh env: BASE_REF: ${{ github.base_ref }} ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} release: if: github.event_name == 'push' needs: checks runs-on: ubuntu-latest environment: prod permissions: contents: read id-token: write # lets this job request the host's identity token env: REGISTRY: ${{ vars.REGISTRY }} PLATFORM: ${{ vars.PLATFORM }} SCAN_CMD: ${{ vars.SCAN_CMD }} steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version-file: .nvmrc # cloud sign-in step from lesson 34, 35 or 36 goes here - run: bash scripts/ci/build-image.sh - run: bash scripts/ci/sbom.sh - run: bash scripts/ci/scan.sh - run: bash scripts/ci/deploy.shThe four release stages share one job on purpose: ci-out/ holds the digest and the evidence, and a single job keeps it on one workspace. If your agency splits the stages into jobs, upload ci-out/ as an artifact between them and keep the digest check in deploy.sh.
GitHub: signing in to the cloud
The job asks GitHub for a token and the cloud exchanges it. The trust rule on the cloud side must state three things.
| Trust rule field | GitHub’s value | Where you set it |
|---|---|---|
| Issuer | https://token.actions.githubusercontent.com (GHE.com has its own issuer host; GitHub Enterprise Server uses https://HOSTNAME/_services/token) | The identity provider, role or pool in lesson 34, 35 or 36 |
| Subject | a sub such as repo:octo-org/octo-repo:environment:prod; limit it to this repository and the prod environment | The role’s trust condition in lesson 34, 35 or 36 |
| Audience | whatever that cloud’s lesson tells you to expect | The same trust condition |
Repositories created after 2026-07-15 get an immutable default sub that carries the owner and repository IDs, so a rule written from an older example no longer matches. Do not hand-write the new value: print the claims from a job, copy the sub, and record where you copied it from. Lesson 34, 35 and 36 each set up the cloud half. A GitHub Enterprise Server instance does not get the immutable format and must define at least one condition on the token; see the on-prem section below.
To open the pull request from the command line, gh pr create reuses your credential-helper sign-in from lesson 17. Run its --help first, as that lesson’s prompt does.
GitHub: owners and required approval
Put CODEOWNERS in .github/, the repository root or docs/; the first one found in that order is used. The last matching pattern takes precedence, and there are no sections, so list the broad rule first and the specific one after it in the file:
REFERENCE CONFIG .github/CODEOWNERS: team ownership for pipeline and referee paths open reference hide reference Reference file from gov-dev-reference-app; open to inspect or compare with what your agent builds.
# .github/CODEOWNERS* @agency/app-reviewers/scripts/ci/ @agency/pipeline-owners/ci/ @agency/pipeline-owners/.github/ @agency/pipeline-owners/.claude/ @agency/intake-business-owners/package.json @agency/intake-business-owners/vitest.config.ts @agency/intake-business-owners/stryker.config.json @agency/intake-business-owners/scripts/verify-cold.sh @agency/intake-business-owners/scripts/capstone/ @agency/intake-business-owners/scripts/parity/ @agency/intake-business-owners/tests/differential/ @agency/intake-business-owners/tests/parity/ @agency/intake-business-owners/modernization/rules.md @agency/intake-business-owners/modernization/unknowns.md @agency/intake-business-owners/modernization/golden/ @agency/intake-business-owners/modernization/scripts/ @agency/intake-business-owners/modernization/parity/rulings/ @agency/intake-business-owners/modernization/parity/equivalent-mutants.txt @agency/intake-business-owners/modernization/referee-paths.txt @agency/intake-business-owners/modernization/owner-teams.txt @agency/intake-business-owners/modernization/variant.json @agency/intake-business-owners/modernization/supported-variants.json @agency/intake-business-owners/evidence/parity-report.json @agency/intake-business-owners/evidence/evidence-manifest.json @agency/intake-business-ownersThe list is lesson 25’s modernization/referee-paths.txt, one root-anchored line per path, because the check fails on any referee path the file leaves to the default reviewers. The * line is the default and comes first so every later line overrides it; the pipeline paths go to the pipeline owners and the judging files to the intake business owners. Then turn on “Require review from Code Owners” inside the branch protection rule for the integration branch, or in the equivalent ruleset. The file assigns; the setting enforces. Lesson 25’s check-referee, which has an adapter per host, reads this file on a cold clone and fails if a referee path is owned by anyone but a team.
GitHub: branch protection names
GitHub calls the setting a branch protection rule, or a ruleset. By default it blocks force pushes on protected branches, and with signed commits required, “contributors and bots can only push commits that have been signed and verified to the branch”. The exact label text of the required-review and required-status-check options was not on the page read, so copy it from the settings screen rather than from a prompt. Rulesets apply on GitHub Team and GitHub Enterprise plans.
GitHub: the headless review step
Lesson 19’s scripts/ci/review.sh runs as written on the runner, and the referee check-review.mjs judges the artifact it writes. GitHub is the one host with official actions for the agent CLIs: anthropics/claude-code-action@v1 and openai/codex-action@v1. If you use one, keep the three decisions from lesson 19: read-only tools, a job without id-token: write, and the referee on the findings file. This lesson does not list an action’s inputs because the research behind it did not cover them; read the action’s page. Claude Code’s separate GitHub code review writes findings and a check run and never approves or blocks.
GitLab: the pipeline file
Three stages. Merge request pipelines run check and review; the integration branch runs release, and only that job asks for an identity token.
REFERENCE CONFIG .gitlab-ci.yml: GitLab CI pipeline delegating to scripts/ci/ open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
stages: [check, review, release]
default: image: $CI_NODE_IMAGE # set to the image your agency mirrors
.on-change: rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' - if: '$CI_COMMIT_BRANCH == "develop"'
lint: extends: .on-change stage: check script: [bash scripts/ci/lint.sh]
typecheck: extends: .on-change stage: check script: [bash scripts/ci/typecheck.sh]
unit: extends: .on-change stage: check script: [bash scripts/ci/unit.sh]
contract: extends: .on-change stage: check script: [bash scripts/ci/contract.sh]
review: stage: review rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' variables: GIT_DEPTH: "0" BASE_REF: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME script: - git fetch origin "$BASE_REF" - bash scripts/ci/review.sh # no id_tokens in this job artifacts: when: always paths: [ci-out/]
release: stage: release rules: - if: '$CI_COMMIT_BRANCH == "develop"' id_tokens: CLOUD_OIDC_TOKEN: aud: "https://cloud-trust-audience.example" script: - echo "cloud sign-in with CLOUD_OIDC_TOKEN goes here (lesson 34, 35 or 36)" - bash scripts/ci/build-image.sh - bash scripts/ci/sbom.sh - bash scripts/ci/scan.sh - bash scripts/ci/deploy.shbuild-image.sh needs a runner that can build and push an image, which is a runner decision for your platform team. The aud: value is a placeholder: use the audience your cloud lesson says the trust rule expects.
GitLab: signing in to the cloud
The id_tokens: keyword with aud: is how a job asks for a token.
| Trust rule field | GitLab’s value | Where you set it |
|---|---|---|
| Issuer | the address of your GitLab instance, such as https://gitlab.com, which the cloud must be able to reach | The identity provider, role or pool in lesson 34, 35 or 36 |
| Subject | print the claims from a job and copy the sub; extended sub fields exist on recent GitLab versions | The role’s trust condition |
| Audience | the aud: you wrote in the job | The same trust condition |
The issuer must be publicly accessible. A self-managed GitLab behind the agency firewall cannot be the identity provider for a cloud trust on a public endpoint unless you expose its discovery and key (JWKS) URLs, which is a decision for your ISSO (the security officer who signs off on your system’s controls). The on-prem section below returns to it.
glab mr create opens the merge request from the command line; run its --help first.
GitLab: owners and required approval
CODEOWNERS goes in the root, docs/ or .gitlab/, and the first found is used. The last matching entry wins. GitLab adds sections: [Section] groups paths under default owners, sections with the same name combine, and ^[Section] makes a section optional in the file:
REFERENCE CONFIG CODEOWNERS: GitLab section-based team ownership for pipeline and referee paths open reference hide reference Reference file from gov-dev-reference-app; open to inspect or compare with what your agent builds.
# CODEOWNERS[Application]* @agency/app-reviewers
[Pipeline and referee paths]/scripts/ci/ @agency/pipeline-owners/ci/ @agency/pipeline-owners/.gitlab-ci.yml @agency/pipeline-owners/CODEOWNERS @agency/pipeline-owners/.claude/ @agency/intake-business-owners/package.json @agency/intake-business-owners/vitest.config.ts @agency/intake-business-owners/stryker.config.json @agency/intake-business-owners/scripts/verify-cold.sh @agency/intake-business-owners/scripts/capstone/ @agency/intake-business-owners/scripts/parity/ @agency/intake-business-owners/tests/differential/ @agency/intake-business-owners/tests/parity/ @agency/intake-business-owners/modernization/rules.md @agency/intake-business-owners/modernization/unknowns.md @agency/intake-business-owners/modernization/golden/ @agency/intake-business-owners/modernization/scripts/ @agency/intake-business-owners/modernization/parity/rulings/ @agency/intake-business-owners/modernization/parity/equivalent-mutants.txt @agency/intake-business-owners/modernization/referee-paths.txt @agency/intake-business-owners/modernization/owner-teams.txt @agency/intake-business-owners/modernization/variant.json @agency/intake-business-owners/modernization/supported-variants.json @agency/intake-business-owners/evidence/parity-report.json @agency/intake-business-owners/evidence/evidence-manifest.json @agency/intake-business-ownersThen turn on “Required approval from code owners” on the protected branch. That setting is Premium and Ultimate; on a lower tier the file only suggests reviewers, so use the compensating procedure in the Bitbucket panel.
GitLab: branch protection names
Protected branches are in every tier. The settings are “Allowed to merge”, “Allowed to push and merge” and “Allowed to force push”. The merge request setting “Status checks must succeed” is Ultimate, and the push rule “Commit must be signed” is Premium and Ultimate. The label for requiring a successful pipeline was not in the page read, so copy it from the settings screen.
GitLab: the headless review step
Claude Code has a GitLab integration in beta, maintained by GitLab, which runs the CLI in a job. For every other CLI, install it on the runner and call scripts/ci/review.sh as the job above does. Codex has no GitLab job in the research, and a GitLab merge request review exists in its cloud code review as a preview. Either way the job has no id_tokens: and the referee judges ci-out/findings.json.
Azure DevOps: the pipeline file
Three stages. The review stage runs for pull requests only, and the release stage runs on the integration branch through a service connection (Azure DevOps’s stored link to a cloud account; with workload identity federation it holds a trust rule, not a key).
REFERENCE CONFIG azure-pipelines.yml: Azure Pipelines stages delegating to scripts/ci/ open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
trigger: branches: include: [develop]pr: branches: include: [develop]pool: vmImage: ubuntu-lateststages: - stage: check jobs: - job: checks steps: - script: bash scripts/ci/lint.sh displayName: lint - script: bash scripts/ci/typecheck.sh displayName: typecheck - script: bash scripts/ci/unit.sh displayName: unit - script: bash scripts/ci/contract.sh displayName: contract - stage: review dependsOn: [] condition: eq(variables['Build.Reason'], 'PullRequest') jobs: - job: review steps: - checkout: self fetchDepth: 0 # install the agent CLI your agency approved (lesson 1) on the agent - script: bash scripts/ci/review.sh displayName: headless review env: BASE_REF: $(System.PullRequest.TargetBranchName) - stage: release dependsOn: check condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/develop')) jobs: - job: release steps: - task: AzureCLI@2 displayName: build, evidence, scan, deploy inputs: azureSubscription: $(SERVICE_CONNECTION) scriptType: bash scriptLocation: inlineScript inlineScript: | set -euo pipefail bash scripts/ci/build-image.sh bash scripts/ci/sbom.sh bash scripts/ci/scan.sh bash scripts/ci/deploy.sh env: REGISTRY: $(REGISTRY) PLATFORM: $(PLATFORM) SCAN_CMD: $(SCAN_CMD)This is the only host here that reaches the cloud through a service connection rather than through a token the job requests itself.
Azure DevOps: signing in to the cloud
Microsoft’s recommendation is a workload identity federation service connection, with either an app registration or a managed identity. For Azure US Government the setup is manual, and the issuer note matters.
| Trust rule field | Azure DevOps’s value | Where you set it |
|---|---|---|
| Issuer | the Azure DevOps issuer, https://vstoken.dev.azure.com, for Azure US Government connections; new public-cloud connections move to a Microsoft Entra issuer on a date in the status box | The federated credential in lesson 34 |
| Subject | entered as an “Explicit subject identifier”; the exact string is UNVERIFIED in the sources, so take it from Microsoft’s page and record where you took it | The same credential |
| Audience | the cloud lesson’s value | The same credential |
Lesson 34 sets up the cloud half for Azure Government, with the manual credential type “Other issuer”. The sources hold no verified path from Azure Pipelines to AWS GovCloud or to Google Cloud, so lessons 35 and 36 do not claim one; treat that route as NOT RUN until you have tried it and written down the trust rule that worked.
az repos pr create opens the pull request from the command line; run its --help first.
Azure DevOps: owners and required approval
There is no CODEOWNERS file in the documentation read. The equivalent is the “Automatically included reviewers” branch policy, with a path filter, set to Required. A path filter must start with / or a wildcard. Create one policy per owner group:
| Path filter | Reviewer group | Policy setting |
|---|---|---|
/scripts/ci/* | the pipeline owners group | Required |
/ci/* | the pipeline owners group | Required |
/azure-pipelines.yml | the pipeline owners group | Required |
each other path in modernization/referee-paths.txt (for example /tests/differential/*, /modernization/golden/*, /modernization/referee-paths.txt, /package.json, /.claude/*) | the intake business owners group | Required |
Policies live on the host, not in the repository, so export them into docs/adr/ with their date, once for each protected branch the lesson uses (develop and main): REFEREE_BRANCH=develop; az repos policy list --branch "$REFEREE_BRANCH" --output json > ci-out/branch-policies.json, then the same with main. Lesson 25’s check reads one branch at a time, selected by REFEREE_BRANCH. Lesson 25’s check-referee, which has an adapter per host, compares the required-reviewer path filters with modernization/referee-paths.txt. Whether the plan tier limits the required-reviewer policy is UNVERIFIED.
Azure DevOps: branch protection names
Azure DevOps calls them branch policies. The names to look for are “Require a minimum number of reviewers”, “Check for linked work items”, “Check for comment resolution”, “Limit merge types”, “Add Build Validation policies”, “Add Status Check policies” and “Automatically included reviewers”. Under review options, set “Prohibit the most recent pusher from approving their own changes” and “Reset all approval votes”. Restrict the bypass permissions “Bypass policies when completing pull requests” and “Bypass policies when pushing” to a named group. Force-push and signed-commit handling are not in the page read; check them on your instance.
Azure DevOps: the headless review step
No documented agent integration was found for Azure Pipelines, and that negative is not exhaustively verified. Say so in your design record, install the CLI on the agent, and call scripts/ci/review.sh as the review stage above does. A build validation policy makes the stage a requirement of the pull request, and the referee still judges the artifact, not the exit code. Copilot code review for Azure DevOps was in public preview when the research was done; the review step in this lesson does not depend on it.
Bitbucket: the pipeline file
Bitbucket calls the file bitbucket-pipelines.yml. A step with oidc: true receives the identity token; give it to the release step only.
REFERENCE CONFIG bitbucket-pipelines.yml: Bitbucket Pipelines config delegating to scripts/ci/ open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
image: node:lts
definitions: steps: - step: &checks name: checks script: - bash scripts/ci/lint.sh - bash scripts/ci/typecheck.sh - bash scripts/ci/unit.sh - bash scripts/ci/contract.sh
pipelines: pull-requests: '**': - step: *checks - step: name: review script: - export BASE_REF="$BITBUCKET_PR_DESTINATION_BRANCH" - git fetch origin "$BASE_REF" - bash scripts/ci/review.sh - step: name: owner approval script: - export BASE_REF="$BITBUCKET_PR_DESTINATION_BRANCH" - git fetch origin "$BASE_REF" # OWNERS_FILE and APPROVERS_FILE: a step you write against Bitbucket's pull request API (not shown, NOT RUN) - export OWNERS_FILE=ci-out/owners.txt APPROVERS_FILE=ci-out/approvers.txt - bash scripts/ci/referee-approval.sh branches: develop: - step: *checks - step: name: release oidc: true # puts BITBUCKET_STEP_OIDC_TOKEN in this step only services: [docker] script: - echo "cloud sign-in with BITBUCKET_STEP_OIDC_TOKEN goes here (lesson 34, 35 or 36)" - bash scripts/ci/build-image.sh - bash scripts/ci/sbom.sh - bash scripts/ci/scan.sh - bash scripts/ci/deploy.shBitbucket: signing in to the cloud
| Trust rule field | Bitbucket’s value | Where you set it |
|---|---|---|
| Issuer | the workspace’s OIDC provider, whose path in Atlassian’s AWS guide ends workspaces/{WORKSPACE}/pipelines-config/identity/oidc | The identity provider, role or pool in lesson 34, 35 or 36 |
| Subject | {REPOSITORY_UUID}[:{ENVIRONMENT_UUID}]:{STEP_UUID}; the repository UUID is stable, and the step UUID changes with the step | The role’s trust condition |
| Audience | “the client ID issued by the Identity provider for your app” | The same trust condition |
The only Bitbucket source with a cloud on it is Atlassian’s AWS page, and it does not mention GovCloud. The routes to Azure Government and to Google Cloud are NOT RUN in this lesson. Bitbucket Cloud has no first-party pull request command line in the sources read, so open the pull request in the browser.
Bitbucket: owners and required approval
Put the file at .bitbucket/CODEOWNERS. The last matching pattern has the highest precedence.
REFERENCE CONFIG .bitbucket/CODEOWNERS: Bitbucket team ownership for pipeline and referee paths open reference hide reference Reference file from gov-dev-reference-app; open to inspect or compare with what your agent builds.
# .bitbucket/CODEOWNERS* @app-reviewers/scripts/ci/ @pipeline-owners/ci/ @pipeline-owners/bitbucket-pipelines.yml @pipeline-owners/.bitbucket/CODEOWNERS @pipeline-owners/.claude/ @intake-business-owners/package.json @intake-business-owners/vitest.config.ts @intake-business-owners/stryker.config.json @intake-business-owners/scripts/verify-cold.sh @intake-business-owners/scripts/capstone/ @intake-business-owners/scripts/parity/ @intake-business-owners/tests/differential/ @intake-business-owners/tests/parity/ @intake-business-owners/modernization/rules.md @intake-business-owners/modernization/unknowns.md @intake-business-owners/modernization/golden/ @intake-business-owners/modernization/scripts/ @intake-business-owners/modernization/parity/rulings/ @intake-business-owners/modernization/parity/equivalent-mutants.txt @intake-business-owners/modernization/referee-paths.txt @intake-business-owners/modernization/owner-teams.txt @intake-business-owners/modernization/variant.json @intake-business-owners/modernization/supported-variants.json @intake-business-owners/evidence/parity-report.json @intake-business-owners/evidence/evidence-manifest.json @intake-business-ownersThe file suggests reviewers. No native setting that requires code-owner approval was found, so on Bitbucket the owner file is advice until you add enforcement. The compensating procedure has four parts, and all four are needed:
- Set default reviewers on the repository to the owner groups, and set the merge checks “Minimum number of approvals” and “Minimum number of approvals from default reviewers”.
- Run a CI check that fails a pull request touching a referee path unless someone in the owner group approved it. A script for the check, which runs on a laptop as well:
REFERENCE CODE scripts/ci/referee-approval.sh: compensating owner-approval gate for referee paths open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
#!/usr/bin/env bash# For hosts with no native "require code-owner approval" setting.set -euo pipefail: "${BASE_REF:?set BASE_REF to the branch the PR targets}"OWNERS_FILE="${OWNERS_FILE:-ci-out/owners.txt}" # the owner group, one user per lineAPPROVERS_FILE="${APPROVERS_FILE:-ci-out/approvers.txt}" # who approved this PR, one user per line
# Capture the diff first: a git that fails (for example a missing base ref) must stop the check.# --no-renames: a file moved OUT of a referee path must show its old path too.if ! changed_files=$(git diff --no-renames --name-only "origin/$BASE_REF"...HEAD); then echo "referee-approval: REFUSED could not diff against origin/$BASE_REF" >&2 exit 1fi# Referee paths without comments or blank lines; an empty prefix would match every file.prefixes=$(sed -e 's/#.*//' -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' modernization/referee-paths.txt | grep -v '^$' || true)
touched=""while IFS= read -r changed; do [ -n "$changed" ] || continue while IFS= read -r prefix; do [ -n "$prefix" ] || continue case "$changed" in "$prefix"*) touched="$touched $changed";; esac done <<< "$prefixes"done <<< "$changed_files"
if [ -z "$touched" ]; then echo "referee-approval: PASS no referee path touched" exit 0fiowners=$(grep -v '^[[:space:]]*$' "$OWNERS_FILE" || true) # a blank line would match a blank approver lineif [ -n "$owners" ] && grep -qxFf <(printf '%s\n' "$owners") <(grep -v '^[[:space:]]*$' "$APPROVERS_FILE"); then echo "referee-approval: PASS an owner approved a change to:$touched"else echo "referee-approval: REFUSED no owner approval for:$touched" >&2 exit 1fi- Make the check’s result stale-proof: a pipeline result is a snapshot, so re-run the check after the owner approves, and put the script under the same owners it protects (
scripts/ci/is in the list above). - Name one person who audits the merges to the integration branch every week and compares each merged change to a referee path with its approvals. The check narrows the gap; the audit is what covers the rest.
Where the approvers come from is a call to Bitbucket’s API that this lesson has no verified source for, so the step that writes APPROVERS_FILE is marked NOT RUN until you have written and tried it.
Bitbucket: branch protection names
The merge checks named in the sources are “Minimum number of approvals” and “Minimum number of approvals from default reviewers”. The Cloud branch restrictions page returned 404, so the names of the branch restrictions are UNVERIFIED; copy them from the settings screen. For Bitbucket Data Center, the CODEOWNERS file under .bitbucket is documented, and owners are added as suggested reviewers; enforcement is UNVERIFIED, and third-party apps are reported to add an owner merge check.
Bitbucket: the headless review step
No agent CLI has an official Bitbucket integration in the research. Install the CLI on the runner and call scripts/ci/review.sh as the review step above does. The step has no oidc: true, so it holds no cloud identity, and the referee judges the artifact.
On-prem and air-gapped hosts
A cloud trust rule needs the cloud to read the issuer’s public keys. That is trivial for a hosted code host and a design question for one inside your network.
- GitLab self-managed. The issuer is your instance’s address and must be publicly accessible. Behind the agency firewall you have two honest options: expose only the discovery and key URLs and nothing else (your ISSO decides), or keep the release job from federating and deploy from a runner inside the boundary that holds a credential your cloud issues there. The second option is a design, not a documented path; this lesson has no source that proves it works.
- GitHub Enterprise Server. The issuer is
https://HOSTNAME/_services/token, you must define at least one condition on the token, and the immutablesubformat is not available on it. A trust rule written for github.com does not carry over. - Azure DevOps Server. The self-hosted edition. The sources for this lesson cover the Services edition’s federation; an Azure DevOps Server federation path is NOT RUN and has no source here.
- Bitbucket Data Center. The owner file is documented and enforcement is not verified; no Pipelines OIDC page was read.
In every case the stage scripts do not change. Only the dialect and the trust path do, which is the reason the logic lives in scripts/ci/.
Vendor FedRAMP statements, read from vendor pages. FedRAMP is the federal program that certifies cloud services; an agency still grants its own authority to operate (ATO). A vendor statement is not an authorization for your system. Only one of these four is VERIFIED.
GitLab: VERIFIED for GitLab Dedicated for Government only. The page lists FedRAMP Moderate: “Meets federal security requirements for cloud services, with Authority to Operate (ATO).” It lists no High level: https://docs.gitlab.com/subscriptions/gitlab_dedicated_for_government/ (no date shown). The gitlab.com SaaS statement is UNVERIFIED.
GitHub: UNVERIFIED for GHE.com. The FAQ says “GitHub Enterprise Cloud is now FedRAMP Authorized” for FedRAMP Tailored, which is for “low risk Software as a Service (SaaS) systems”, with no date shown: https://government.github.com/fedramp-faq. It does not mention GHE.com, US data residency, Moderate or High.
Azure DevOps Services: UNVERIFIED. Neither Microsoft’s FedRAMP page (ms.date 2023-04-04) nor the Azure DevOps data-protection page (ms.date 2026-03-18) names it.
Bitbucket: UNVERIFIED. A search summary credited a different Atlassian product line, naming Jira, Jira Service Management and Confluence only; the sources were community posts and press mirrors. Treat Bitbucket as not covered.
Recheck the cited source and your agency’s authorization boundary before you rely on any of it.
Plan, wire, repair
- Typed in the terminal:
claude - Mode:Plan mode
- You type in the session: The host in CLAUDE.md is GitHub. Plan the workflow file: checks, review, release. Release is the only job that gets an identity token. Do not edit.
- The tool replies: Plan (read-only, nothing edited): 1. .github/workflows/ci.yml with three jobs. checks runs scripts/ci/lint.sh, typecheck.sh, unit.sh and contract.sh. review runs on pull requests only, with contents: read and no id-token. release runs on pushes only, with id-token: write and environment prod. 2. .github/CODEOWNERS covering every path in modernization/referee-paths.txt, owned by teams. 3. The cloud sign-in step is a placeholder: lesson 34, 35 or 36 owns it. Not certain of: the exact label of the required-review option in branch protection (I will not guess it), and whether your agency allows actions pinned by tag or requires a commit hash. Approve?
- Mode:Plan approved: plan mode off
- You type in the session: Approved. Write both files and parse the YAML.
- The tool replies: Wrote .github/workflows/ci.yml and .github/CODEOWNERS. $ python3 -c 'import yaml,sys; yaml.safe_load(open(sys.argv[1]))' .github/workflows/ci.yml $ echo $? 0 The file parses. That proves the syntax and nothing else: whether GitHub accepts the keys, and whether the trust rule matches the token, only a run on GitHub shows. I have marked those NOT RUN in the Prove it table.
- You type in the session: The release job on the new repo fails: no matching federated credential. The trust rule worked on the old repo.
- The tool replies: I will not add a stored key. The token reached the cloud, so the issuer and audience are right; the subject is the likely difference. This repository was created after the date GitHub changed the default subject format, so the rule I copied from the old repo expects a subject that no longer arrives. I added a step to the release job that prints the token's claims (issuer, subject, audience, no secret in them), and I will copy the subject from that log into the trust rule, limited to this repository and the prod environment. I did not widen the rule to a wildcard. After the fix I will record the date and where I copied the subject from, because the next repository will differ again.
- You type in the session: Different project, same stages, but the host is Bitbucket. Make sure nobody can merge a change to scripts/ci without an owner approving.
- The tool replies: Bitbucket's code owners file only suggests reviewers, and I found no native setting that requires owner approval, so a CODEOWNERS file alone would be advice. I wrote scripts/ci/referee-approval.sh and ran it in a temporary git repository against modernization/referee-paths.txt, six cases: $ BASE_REF=develop OWNERS_FILE=owners APPROVERS_FILE=approvers bash scripts/ci/referee-approval.sh # 1. only README.md changed: referee-approval: PASS no referee path touched # 2. scripts/verify-cold.sh changed, empty approvers file: referee-approval: REFUSED no owner approval for: scripts/verify-cold.sh (exit 1) # 3. same change, approver outside the owner group: referee-approval: REFUSED no owner approval for: scripts/verify-cold.sh (exit 1) # 4. same change, an owner in the approvers file: referee-approval: PASS an owner approved a change to: scripts/verify-cold.sh (exit 0) # 5. tests/parity/q.ts changed, empty approvers file: referee-approval: REFUSED no owner approval for: tests/parity/q.ts (exit 1) # 6. BASE_REF names a branch that does not exist: referee-approval: REFUSED could not diff against origin/nosuch (exit 1) What I did not do: write the step that fetches the real approvers from Bitbucket's API. I have no verified source for that call, so it is NOT RUN. Until you write it, the weekly merge audit is the control, and I added the name of the person who does it to docs/adr/.
Illustrative session in Claude Code; the exact wording varies.
Prove it
Runs locally. Extract each pipeline file and parse it. This proves syntax and nothing about the host:
for f in .github/workflows/ci.yml .gitlab-ci.yml azure-pipelines.yml bitbucket-pipelines.yml; do [ -e "$f" ] || continue python3 -c 'import yaml,sys; yaml.safe_load(open(sys.argv[1]))' "$f" && echo "parsed $f"doneThen run the owner-approval check on a throwaway branch. Pass: a change outside the referee paths passes. Fail cases to plant, one at a time: edit a file under scripts/ci/ with an empty approvers file (expect REFUSED, exit 1); then list an approver who is not in the owner group (still REFUSED); then add an owner to the approvers file (PASS, exit 0). If the owners file is empty, the check must refuse; an empty owner list that passes would approve everything.
Needs your host (NOT RUN here). None of these has been run against a live organization for this lesson.
| Check | Action | Expected | Status |
|---|---|---|---|
| Pipeline runs | Push a branch and open a pull request | The check stages run in order, the review job runs, and release does not | NOT RUN |
| Release identity | Push to the integration branch | Only the release job holds the identity token; the cloud sign-in succeeds with no stored key | NOT RUN |
| Trust rule is narrow | Run the release job from a different branch or repository | The cloud refuses the token | NOT RUN |
| Review job holds nothing | Print the environment of the review job | No identity token, no deploy variable | NOT RUN |
| Owner gate | Open a pull request that edits a file under scripts/ci/ with no owner approval | The merge is blocked by the host (GitHub, GitLab, Azure DevOps) or refused by the CI check (Bitbucket) | NOT RUN |
| Bypass | List who can bypass the branch rule | A named group, recorded in docs/adr/ | NOT RUN |
| Weekly audit (Bitbucket) | The named person lists last week’s merges | Every merge to a referee path has an owner approval | NOT RUN |
Your release job worked on an older repository and fails with a trust error on a repository created this month. The issuer and audience are unchanged. What do you check first?
On Bitbucket you add a .bitbucket/CODEOWNERS file listing owners for scripts/ci/. Does that make owner approval required before a merge?
Your agency runs GitLab self-managed behind its firewall and wants the release job to federate to a cloud trust on a public endpoint. What is the constraint?
Practice status
| Practice | Status | Also called |
|---|---|---|
| Pipeline file that only calls versioned stage scripts | strong optional | thin CI, portable pipeline |
| Short-lived identity token to the cloud, no stored key | common baseline | OIDC federation, workload identity federation, keyless deploy |
| Identity token requested by the release job only | strong optional | least-privilege job permissions |
| Trust condition limited to one repository and environment | common baseline | subject pinning, trust condition |
| Owner file plus a host setting that enforces it | common baseline | CODEOWNERS with required review, required reviewers policy |
| CI check on referee paths where the host cannot enforce owners | emerging | compensating control, approval gate |
| Review agent in a job with no cloud identity, judged by a referee | reference-shop | advisory review, sandboxed review job |
Scale: required | common baseline | strong optional | reference-shop (seen only at organizations that publish their own practice) | emerging
Key takeaway
- The pipeline file is a dialect: it calls the stage scripts in order and nothing else, so changing host rewrites one file.
- Only the release job asks for an identity token, and its trust rule names an issuer, a narrow subject and an audience. Print the subject from a job rather than writing it by hand, because the format can change.
- Owner approval is a setting on three of the four hosts and a procedure on the fourth. Wherever a setting is missing, the check and the weekly audit stand in for it, and the procedure is written down.
- The YAML parse and the owner-approval check run on your laptop. Everything that needs your host stays NOT RUN until you run it and record the result.
- LEADERSHIP DECISION
- Which host your agency allows, who may bypass its branch rule, and whether a host with no owner-approval setting is acceptable with a compensating procedure.
- PRACTITIONER ACTION
- Write the pipeline file, narrow the trust rule to one repository and environment, and run the owner-approval check against a planted referee-path change.
- SUCCESS MEASURE
- Audit finding avoided: no merge to a referee path without an owner approval, shown by the host setting or by last week's audit list.
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