Secrets in CI: Workflow and infrastructure
Binds CI jobs to cloud roles through OIDC, forbids long-lived PATs in logs and artifacts, locks secrets to protected environments, and isolates fork pull requests from production credentials.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Continuous integration and delivery assume cloud roles through OpenID Connect from the trusted identity provider of the pipeline, not long-lived personal access tokens stored as repository secrets. Tokens are short-lived and scoped to one job. Production secrets are locked to protected environments with required reviewers. Workflows triggered from fork pull requests never receive production or deploy credentials.
Scope
- OIDC federation, role trust policies, secret inventory, environment protection, log and artifact redaction, fork isolation, and job-scoped credentials for CI/CD of backend services.
- Deploy, migrate, and package jobs that need cloud or registry access.
- Audit of which workflow identities can assume which roles.
Outside this block
- Application runtime secret rotation after deploy.
- Developer workstation credential managers.
Contract
- Deploy and cloud-mutating jobs authenticate with OIDC to a role whose trust policy pins repository, environment, and subject claims; static cloud keys are absent from those jobs.
- Long-lived personal access tokens are not stored for deploy; if a legacy token exists, it is expired and jobs fail closed rather than printing it.
- Pipeline logs, debug traces, and uploaded artifacts are scanned for secret patterns and fail the job when a token-shaped value is detected.
- Production environment secrets are available only after environment protection rules pass, including required reviewers where configured.
- Fork pull requests run in a credential-less context: unit tests may run, deploy roles and production secrets do not.
- Job tokens expire at job end; reuse of an OIDC token from a previous job is rejected by the cloud role.
Implementation guidance
- Follow GitHub Actions OpenID Connect (or the equivalent for GitLab/cloud build) so the workflow requests an ID token and the cloud provider exchanges it for a role.
- Split roles: package-publish, staging-deploy, production-deploy, with production trust limited to the protected environment.
Failure handling
- OIDC exchange failure fails the job; it does not fall back to a PAT from repository secrets.
- A log-scan hit marks the secret compromised: rotate the credential and delete the log batch per retention policy.
Verification and operations
- Inventory workflow files for static AWS keys, PATs, and pull_request_target plus secrets.
- Alert on cloud AssumeRole from subjects outside the allowlisted workflow.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.