Skip to content

ADR-003: CI/CD Platform and Authentication

Context and Problem Statement

The project needed an automated pipeline to lint, test, build, and deploy infrastructure and application containers to Azure on every push to main and on version tags. The pipeline also needed to support PR preview deployments. A choice was required on both the CI/CD platform and the mechanism for authenticating to Azure from the pipeline.

Considered Options

  • Azure DevOps with service principal secrets — mature enterprise CI/CD platform with deep Azure integration. Service connections store a client secret that must be rotated periodically. Separate platform from the source control host (GitHub).

  • GitHub Actions with service principal secrets — pipelines co-located with the code in GitHub. Authentication via AZURE_CLIENT_SECRET stored as a GitHub secret. Secrets are long-lived and must be rotated manually; exposure in logs is a risk if not masked correctly.

  • GitHub Actions with OIDC (Workload Identity Federation) — pipelines use a short-lived OIDC token issued by GitHub to authenticate to Azure via a federated credential on an Entra ID app registration. No long-lived secret is stored anywhere. Each token is scoped to the specific repository, branch, environment, or tag that triggered the run.

Decision Outcome

Chosen option: "GitHub Actions with OIDC". Source control is already on GitHub, so co-locating CI/CD in Actions eliminates a context switch and a separate platform to manage. OIDC eliminates the operational burden of rotating client secrets and removes the risk of secret leakage — the token is issued per-job and expires after the run. Federated credentials are scoped per subject claim (branch, PR, tag, environment), giving fine-grained control over which pipeline runs can deploy to which environment.

Consequences

  • Good, because no long-lived credentials are stored — nothing to rotate, nothing to leak.
  • Good, because the pipeline configuration lives alongside the code in .github/workflows/, making it reviewable and auditable via pull requests.
  • Bad, because OIDC subject claim configuration is non-obvious: each federated credential targets a specific subject pattern (ref:refs/heads/main, ref:refs/tags/*, environment:prod, etc.), and mismatches produce cryptic authentication errors rather than clear messages.
  • Bad, because GitHub Actions free-tier concurrency limits apply; large parallel build matrices may queue. For this project the limits are sufficient.

Page history

Field Value
Last updated —