[IAmJSD]

Root cause

.github/workflows/README.md was not updated when CI moved to OIDC. Its setup guide still told operators to create and store a long-lived credential for each of the three clouds, and no workflow reads any of them:

• Azure: an az ad sp create-for-rbac --sdk-auth JSON stored as AZURE_CREDENTIALS.
• AWS: AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY.
• GCP: a downloaded service-account key stored as GCP_SA_KEY, plus a manual project-wide roles/run.admin grant. The troubleshooting section repeated the grant.

So following the guide only creates the long-lived, exfiltratable credentials the OIDC design is meant to avoid. This covers the original issue and the A14-006 audit addendum.

What the workflows actually read (current main)

Cloud	Action	Inputs (all from .github/workflows/*.yml)
Azure	azure/login (deploy-azure x2, rollback, cleanup-staging, database-migration)	secrets.AZURE_CLIENT_ID, secrets.AZURE_TENANT_ID, secrets.AZURE_SUBSCRIPTION_ID
AWS	aws-actions/configure-aws-credentials (deploy-aws-lambda x2, deploy-aws-fargate, rollback x2, cleanup-staging x2, destroy-fargate-dev, database-migration)	vars.AWS_ROLE_TO_ASSUME, vars.AWS_REGION
GCP	google-github-actions/auth (deploy-gcp, rollback, cleanup-staging, database-migration)	vars.GCP_WORKLOAD_IDENTITY_PROVIDER, vars.GCP_SERVICE_ACCOUNT

No workflow reads a static key, so I removed all of those instructions. None needed to stay.

Fix (docs only, one file, two commits)

1. Per-workflow Required Secrets/Variables
   • AWS Lambda: the access keys are replaced by the workflow's real secrets: ADMIN_EMAIL and TF_BACKEND_AWS, plus optional ALERT_EMAILS, FROM_EMAIL and DASHBOARD_URL. Added the AWS_ROLE_TO_ASSUME variable.
   • GCP: GCP_SA_KEY is replaced by ADMIN_EMAIL and TF_BACKEND_GCP, plus optional ALERT_EMAILS. Added the GCP_WORKLOAD_IDENTITY_PROVIDER and GCP_SERVICE_ACCOUNT variables.
   • Azure: AZURE_CREDENTIALS is replaced by AZURE_CLIENT_ID and AZURE_TENANT_ID. Added ADMIN_EMAIL, TF_BACKEND_AZURE and optional ALERT_EMAILS, matching deploy-azure.yml's workflow_call secrets. Also added the push-to-main trigger and changed the AZURE_LOCATION default to westus2 (the workflow's vars.AZURE_LOCATION || 'westus2').
2. Setup Guide
   • Intro: a shared note that all three clouds use the GitHub OIDC issuer https://token.actions.githubusercontent.com, with the trust coming from the manually applied terraform/environments/*/ci-cd-permissions bootstrap modules.
   • AWS: gh variable set AWS_ROLE_TO_ASSUME from terraform output -raw role_arn, plus the trust from role.tf and github_oidc.tf:
     • Audience: sts.amazonaws.com.
     • Subject: matched with StringEquals against the literal role.tf list.
     • A table maps each environment subject (dev/staging/prod, aws-fargate-*, aws-db-*) to the jobs that present it. All are in role.tf. Its ref:refs/heads/main entry has no current consumer.
   • GCP: gh variable set for the provider and service account from the module outputs, plus the WIF trust from github_oidc.tf:
     • Audience: the default (no allowed_audiences set).
     • Attribute condition: repository_owner_id, repository_id and ref == deploy_ref (default refs/heads/main), with no sub check. GCP jobs therefore authenticate only from deploy_ref, whatever environment they bind.
   • roles/run.admin: the GCP module does still grant it at project level, as one of 22 roles in local.deploy_roles in service_account.tf. The README no longer has a hand-run single-role grant. It now says the SA's roles are that list (terraform output roles), and that you change the list and re-apply the module rather than granting by hand, following the CLAUDE.md bootstrap/runtime split. The GCP "Permission denied" troubleshooting snippet got the same treatment.
   • Azure: issuer and audience (api://AzureADTokenExchange), environment subjects mapped to jobs, and the known azure-db-* gap (migrate-azure fails with AADSTS70021 until those environments are created, gated and added to github_environments).
3. Immutable OIDC subject (correction to my first commit)
   • This repo has use_immutable_subject: true. gh api repos/LeanerCloud/cloud-commitments-platform/actions/oidc/customization/sub returns the prefix repo:LeanerCloud@86753534/cloud-commitments-platform@1391259743.
   • The cristim 2026-10-04 status comment on sec(iac): rename-proof OIDC deploy trust + branch-restricted environments for the split platform repo #2 says the AWS and Azure trust was re-applied against that prefix. The GCP module README on main says the same.
   • The README now documents that prefix, with the gh api command to check it. It explains that the AWS and Azure modules build subjects as repo:<github_repo>:..., so github_repo must be the owner@id/repo@id form.
   • The Azure subject row now uses the prefix. My first commit had the plain-name form, which no token presents.

Verification

This change is docs only, so the evidence comes from grep and lint. Nothing was deployed, no Terraform was applied, and no cloud API was called. The only live call was the read-only gh api .../oidc/customization/sub above.

Fail before, pass after. Pattern: AZURE_CREDENTIALS|sdk-auth|create-for-rbac|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|GCP_SA_KEY|keys create|add-iam-policy-binding|default: eastus

$ git grep -n -E "$P" origin/main -- .github/workflows/README.md
README.md:92:- `AWS_ACCESS_KEY_ID`
README.md:93:- `AWS_SECRET_ACCESS_KEY`
README.md:172:- `GCP_SA_KEY` (Service Account JSON with permissions)
README.md:213:- `AZURE_CREDENTIALS` (Service Principal JSON)
README.md:218:- `AZURE_LOCATION` (default: eastus)
README.md:445:gh secret set AWS_ACCESS_KEY_ID
README.md:446:gh secret set AWS_SECRET_ACCESS_KEY
README.md:457:gcloud projects add-iam-policy-binding <project-id> \
README.md:462:gcloud iam service-accounts keys create key.json \
README.md:466:gh secret set GCP_SA_KEY < key.json
README.md:477:az ad sp create-for-rbac --name cudly-cicd --sdk-auth > azure-credentials.json
README.md:480:gh secret set AZURE_CREDENTIALS < azure-credentials.json
README.md:607:gcloud projects add-iam-policy-binding <project-id> \

$ git grep -n -E "$P" -- .github/workflows/README.md      # this branch
README.md:537:Azure authenticates with OIDC, so no client secret or `--sdk-auth` JSON is created or stored. The

The only remaining hit is the sentence saying --sdk-auth JSON is not created.

No workflow reads a static key. git grep -n -E "AZURE_CREDENTIALS|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|GCP_SA_KEY|credentials_json|aws-access-key-id" -- '.github/workflows/*.yml' returns nothing (exit 1). The only other repo hits are quotes in docs/audits/codebase-audit-2026-09-02.md, a verbatim audit record that markdownlint ignores. I left it unchanged.

Job-to-environment tables: generated by parsing every job in .github/workflows/*.yml that runs one of the three auth actions, with its environment: binding. I checked them against the subject lists in role.tf and sp.tf.

Lint and secret scanning (in a temp dir, using the repo's .markdownlint.yaml):

• npx markdownlint-cli@0.47.0 .github/workflows/README.md (the version pinned in .pre-commit-config.yaml) exits 0.
• npx markdownlint-cli2@0.18.1 reports 0 errors.
• git-secrets: ran scripts/setup-git-secrets.sh and .gitallowed in a fresh git init repo with an isolated HOME (27 patterns registered). git secrets --scan .github/workflows/README.md exits 0.
• scripts/test-git-secrets-allowlist.sh reports 137 PASS, 0 FAIL with exit 0, on two fresh isolated-HOME runs. One earlier run, batched with the setup step, exited 1 without saved output, and I could not reproduce it.

Other checks: the relative link to the Azure bootstrap README resolves, and the file has no trailing whitespace.

Not run, because no Go, YAML or Terraform changed: Go build/test/vet, golangci-lint, gocyclo, actionlint and terraform.

Out of scope / follow-ups

• Bootstrap READMEs and variable docs: the AWS and Azure READMEs and variables.tf descriptions under terraform/environments/*/ci-cd-permissions/ still show github_repo and the subject in the plain LeanerCloud/cloud-commitments-platform form. They don't mention that the immutable prefix is needed, and the Terraform defaults still use the plain name. Rename-proof trust is tracked in sec(iac): rename-proof OIDC deploy trust + branch-restricted environments for the split platform repo #2.
• Other README drift, unrelated to credentials:
  • The GCP deployment "Triggers" list omits push-to-main.
  • The AWS Lambda "Required Variables" still lists AWS_ACCOUNT_ID/ECR_REPOSITORY, which deploy-aws-lambda.yml doesn't read.
  • The AWS Fargate section's "Same as AWS Lambda" secrets line now includes Lambda-only optional secrets.
• Gap left as is: the azure-db-* federated credentials themselves, the existing bootstrap-module gap, are documented but not created here.

Maintainer: please mirror the issue's triage labels on this PR: impact/internal, triaged, priority/p3, severity/low, urgency/eventually, effort/xs, type/docs.

Closes #28

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

• Run on-demand review

_{This review includes 1 billable file and costs up to $0.25.}

Or wait 57 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

• Source mode: Auto
• Repository: LeanerCloud/cloud-commitments-platform
• Branch: main
• File: .coderabbit.yaml
• Commit: 2f1dbca
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Advanced
• Run ID: 674437c2-f3aa-4bf0-8201-862ed551f8b3

Commits

Reviewing files that changed from the base of the PR and between 2f1dbca and fcf7915.

Files selected for processing: 1

• .github/workflows/README.md

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[cristim]

Independent review 2 (claude-fleet, cold): APPROVE fcf7915

Every trust claim in the new text matches the workflows and IaC, in both the head and the merged tree. None is weaker than the IaC, and nothing tells anyone to create a long-lived key.

Findings (none blocking):

• [non-blocking] .github/workflows/README.md:569-571 - The text says migrate-azure fails "until those environments exist with protection rules and are added to github_environments". After the merge, that is half stale:
  • The github_environments description now on main (terraform/environments/azure/ci-cd-permissions/variables.tf) says the azure-db-* environments already exist with a main-only branch policy.
  • Only the github_environments addition (#1648) is still open.
  • The outcome the README describes is still correct.
• [non-blocking, follow-up] README:571 sends readers to "step 3 below" (README:605ff, unchanged). Step 3 still says Dev environments get "no restrictions", which contradicts the gating rule now on main. The contradiction predates this PR, but the new cross-reference points readers at it.
• [non-blocking, follow-up] "Drop static-key setup" is incomplete repo-wide. docs/DEPLOYMENT.md:381-382 and terraform/modules/frontend/README.md:365-366 still show secrets.AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY. Both are outside this file.
• [nit] README:103-104 (pre-existing) lists AWS_ACCOUNT_ID and ECR_REPOSITORY as required Lambda variables. deploy-aws-lambda.yml does not read them; only rollback.yml:105-106 does.
• [non-blocking] The AWS trust table (README:487-491) omits the optional trust_principal human-IAM statement (role.tf:10-14). That omission weakens nothing.

Claims checked against source:

• OIDC provider URL: github_oidc.tf:4 (AWS), gcp github_oidc.tf:19 and azure sp.tf:46,76.
• AWS:
  • The role cudly-terraform-deploy (role.tf:4).
  • aud=sts.amazonaws.com with StringEquals (role.tf:23-24).
  • sub is a literal list (role.tf:91-128) of main, dev/staging/prod, aws-fargate-* and aws-db-*.
  • The output role_arn (outputs.tf:1).
• The AWS job-to-environment table, line by line:
  • deploy-aws-lambda.yml:237,390, with the allowlist at :147-153;
  • deploy-aws-fargate.yml:153-154;
  • database-migration.yml:291-292;
  • rollback.yml:225,332;
  • cleanup-staging.yml:114,198;
  • destroy-fargate-dev.yml:93.
  • Every AWS-assuming job is bound to an environment, so "the main subject is unused" holds.
• id-token: write: present on all 15 credential-exchanging jobs. The two test-deployment jobs without it (deploy-aws-fargate.yml:275, deploy-gcp.yml:260) are correctly left out of the tables.
• GCP:
  • The SA cudly-terraform-deploy (service_account.tf:41) and the pool/provider (github_oidc.tf:1-43).
  • The condition is on owner_id, repo_id and ref == deploy_ref, which defaults to refs/heads/main (github_oidc.tf:42, variables.tf:37-40).
  • No allowed_audiences is set, and sub is not matched.
  • The binding is on attribute.repository_id (github_oidc.tf:46-51).
  • The outputs match, and run.admin is in deploy_roles. The workflows read vars.GCP_WORKLOAD_IDENTITY_PROVIDER and vars.GCP_SERVICE_ACCOUNT.
• Azure:
  • The audience api://AzureADTokenExchange, the subjects (sp.tf:45-47,75-77) and the default environments dev/staging/prod.
  • The client_id/tenant_id outputs.
  • The AZURE_CLIENT_ID, AZURE_TENANT_ID and AZURE_SUBSCRIPTION_ID secrets (deploy-azure.yml:187-189).
  • The AZURE_LOCATION default westus2 (:66), and the push-to-main trigger (:36-37).
• Immutable-subject prefix: the owner/repo IDs match the gcp terraform.tfvars.example:40-41 and tests/immutable_trust.tftest.hcl:11-12. The format matches the gcp README. I could not confirm the live repo setting (no API calls). If the setting were off, AWS and Azure would fail to authenticate rather than accept extra subjects.
• Secrets and variables, and links:
  • The TF_BACKEND_, ADMIN_EMAIL/ALERT_EMAILS/FROM_EMAIL/DASHBOARD_URL and DB_PASSWORD_ names are all referenced by the workflows.
  • The ci-cd-permissions README link and the #setup-guide anchor both resolve.

Verified locally:

• git merge-tree --write-tree origin/main fcf7915c against origin/main 6af022f: clean.
• markdownlint -c .markdownlint.yaml .github/workflows/README.md: rc 0 on base, head and the merged file.
• Lint probes, on a scratch copy:
  • A missing blank line before a fence is caught by MD031.
  • A compact |Field|Value| row passes. That is a lint coverage gap, not something this PR introduces.
• No em-dashes, and no account or subscription IDs are added. The numeric IDs are GitHub owner/repo IDs that are already in the repo.

Reviewed by an independent agent with no author context (second reviewer). Review only: nothing was pushed, and the GitHub review state is unchanged.

[cristim]

VERDICT: APPROVE fcf7915

Docs-only change to .github/workflows/README.md. It fixes #28 including the A14-006 addendum: every static-credential instruction (AZURE_CREDENTIALS / --sdk-auth, AWS access keys, GCP SA key plus the hand-run roles/run.admin grant) is gone, and the replacement OIDC setup matches the workflows and bootstrap modules. Merges cleanly onto current origin/main (merge-tree exit 0), and also merges cleanly stacked with #1228.

Findings (none blocking):

• nit .github/workflows/README.md:470,550 (and the GCP block) - the setup blocks still say gh secret set DB_PASSWORD_{AWS,GCP,AZURE}, but no workflow reads those secrets (only ci.yml's throwaway DB_PASSWORD). This predates the PR, but it is the same kind of drift.
• nit .github/workflows/README.md "2. Configure GitHub Variables" - still runs gh variable set AZURE_LOCATION -b"eastus". Correct as an explicit override, but it now reads oddly next to the documented default westus2.
• nit - AWS_ACCOUNT_ID / ECR_REPOSITORY are still listed as required Lambda variables but not read. The PR body already lists this as a follow-up.

Attacked:

• Per-workflow secret/variable lists, grepped (secrets|vars).X in deploy-aws-lambda.yml, deploy-gcp.yml and deploy-azure.yml. Each README list matches exactly, optional markers included. Azure push-to-main trigger: deploy-azure.yml:37. westus2 default: deploy-azure.yml:66.
• Terraform output names used in the gh variable/secret set commands: aws outputs.tf:1 role_arn; gcp outputs.tf:1,11,16 service_account_email, roles, workload_identity_provider; azure outputs.tf:11,21 client_id, tenant_id. All exist.
• AWS trust: github_oidc.tf issuer and client_id_list = sts.amazonaws.com. role.tf:23-24 has StringEquals on aud, and the subject list includes ref:refs/heads/main plus the nine environment subjects documented.
• GCP trust: github_oidc.tf attribute_condition is owner_id, repo_id and ref == deploy_ref, with no sub and no allowed_audiences. deploy_roles in service_account.tf contains roles/run.admin.
• Azure: sp.tf audience api://AzureADTokenExchange, the github_main credential, and per-environment credentials from github_environments (default dev/staging/prod). The documented azure-db-* gap matches variables.tf.
• Job-to-environment tables: parsed every workflow job that uses azure/login, configure-aws-credentials or google-github-actions/auth together with its environment:. The AWS and Azure tables and the GCP job list match exactly.
• Immutable subject claim, checked live and read-only: gh api .../actions/oidc/customization/sub returns use_immutable_subject: true with the documented prefix. The repo and owner ids match the repository API. These are public GitHub ids, not cloud identifiers.
• Fail-before/pass-after: a grep for the stale-credential patterns finds 13 hits on origin/main. On the head, the only hit is the sentence saying --sdk-auth JSON is not created.
• markdownlint-cli@0.47.0 -c .markdownlint.yaml on the head file: exit 0. The relative link to the Azure bootstrap README resolves.
• Closing refs: closingIssuesReferences is [28], as intended.
• Mutation probes: not applicable to a docs-only diff. The grep fail-before/pass-after above stands in for them.

[IAmJSD]

Independent review (IAmJSD's agent, fresh context, given only the diff, the issue and the PR text): VERDICT: APPROVE fcf7915c422dcddb6dd9b766678ec82cdb5e9fb4

Blocking:

• none

Non-blocking:

• .github/workflows/deploy-azure.yml:14: the header comment still gives AZURE_LOCATION as "e.g., eastus", while the effective default is westus2, which the README now states. Cosmetic and outside this file's diff.
• Other drift the PR already lists as out of scope (AWS_ACCOUNT_ID/ECR_REPOSITORY under Lambda Required Variables, the bootstrap module READMEs still showing the plain github_repo form) is fine as follow-ups. The github_repo one matters most: someone re-applying the AWS/Azure bootstrap with the default would mint subjects no token presents. It's worth its own issue if sec(iac): rename-proof OIDC deploy trust + branch-restricted environments for the split platform repo #2 doesn't already cover it.
• (From an earlier review, which I confirmed on current origin/main.) Static AWS keys are still shown outside this file: docs/DEPLOYMENT.md:381 (aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}) and terraform/modules/frontend/README.md:365. docs(ci): scrub stale AZURE_CREDENTIALS references from workflows README (post-OIDC #538) #28/A14-006 scopes itself to this README, so this is a follow-up, not a blocker.
• One earlier review's nit says no workflow reads DB_PASSWORD_{AWS,GCP,AZURE}. That is incorrect: database-migration.yml:369,410,500,607 read them as PGPASSWORD, so keeping gh secret set DB_PASSWORD_* in the guide is right.

Attacked:

• Checked every factual claim against the tree, not the PR body. Secrets and vars come from grep -oE 'secrets\.|vars\.' on deploy-aws-lambda.yml, deploy-gcp.yml and deploy-azure.yml (exact match, including westus2 and the push-to-main trigger). The job-to-environment tables came from a PyYAML walk of every job that uses configure-aws-credentials, google-github-actions/auth or azure/login, and all rows match. The AWS trust (StringEquals, aud=sts.amazonaws.com, the literal sub list including ref:refs/heads/main) matches role.tf. The GCP attribute_condition (owner id, repo id, ref == deploy_ref, no allowed_audiences) matches github_oidc.tf. The Azure audience/issuer/subjects and the extra ref:refs/heads/main credential match sp.tf. terraform output names (role_arn, workload_identity_provider, service_account_email, roles, client_id, tenant_id) all exist, and roles/run.admin is in the 22-role deploy_roles list.
• Ran gh api repos/LeanerCloud/cloud-commitments-platform/actions/oidc/customization/sub (read-only): use_immutable_subject: true with prefix repo:LeanerCloud@86753534/cloud-commitments-platform@1391259743, as documented.
• No workflow reads AZURE_CREDENTIALS, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY or GCP_SA_KEY. DB_PASSWORD_* (kept in the guide) is read by database-migration.yml. The relative link to the Azure bootstrap README resolves. Docs-only, so no Go checks apply. git merge-tree against origin/main and against chore(ci): drop the unreachable Fargate caller job from deploy-all (#314) #1228 (which edits the same README) is clean.

Body-stale: none

_{Reviewer: rB3. Bar while the maintainers are away (set by IAmJSD as acting owner): one approving independent review on the head, two for money, auth and security paths.}

[IAmJSD]

Local verification at fcf7915c422dcddb6dd9b766678ec82cdb5e9fb4 merged onto main (5aa3df5b), together with #1155, #1219, #1221, #1223, #1224, #1225, #1226, #1227, #1256, #1262, #1266, #1270, #1272, #1275, #1283, #1286, #1293, #1297, #1299, #1300, #1301, #1304, #1307, #1311, #1313, #1325 in that order (combined tree f3a3331f, Linux, Go 1.26.10): go build ./..., go vet with and without -tags integration, the full go test -race -short -count=1 ./..., and go test -race -tags integration -count=1 on every changed package, against Docker Postgres. All pass. CI Success and pre-commit are green on this head, with 2 approving independent review(s) on it. Nothing was run against any cloud.

[IAmJSD]

Merged by IAmJSD's agent at IAmJSD's request (IAmJSD is acting owner while the maintainers are away), under the bar IAmJSD set: 2 approving independent review(s) on fcf7915c, green CI, and the combined-tree verification above. Squash-merged at exactly fcf7915c422dcddb6dd9b766678ec82cdb5e9fb4.