GitHub Actions OIDC¶

Engineering Deep Dive R1 Workplace R2 Delivery R2 Network R2 Platform R2 Operations

Scope

Delivery-control notes and evidence paths for the GitHub Actions OIDC model used in Release 2, including authentication flow, workflow boundaries, and controlled Terraform execution. The page focuses on OIDC, bounded Terraform execution, plan-review-apply separation, and controlled apply behavior.

Delivery model¶

Release 2 uses GitHub Actions as the normal Terraform delivery path.

The delivery model is different from a local-apply workflow. A local Terraform plan can support validation, but infrastructure mutation flows through controlled GitHub Actions workflows using OpenID Connect and explicit review.

Design choice	Engineering rationale	Evidence path
Use GitHub Actions OIDC instead of static cloud deployment secrets	Reduces long-lived credential exposure and removes routine secret rotation from the deployment path.	Terraform state and pipeline map
Use `id-token: write` and `azure/login@v2`	Allows GitHub Actions to request an OIDC token and exchange it for an Azure access token at runtime.	Release 2 Terraform CI workflow
Keep plan and apply as separate control points	Terraform plan output is reviewed before apply, preventing unreviewed infrastructure mutation.	Terraform state and pipeline map
Prefer root-specific apply workflows	Keeps apply scope bounded to the selected platform root rather than using a generic multi-root apply workflow.	Disabled generic apply workflow
Require explicit apply confirmation for sensitive roots	Prevents plan execution from automatically becoming infrastructure mutation.	Platform networking hybrid apply workflow

Authentication flow¶

The OIDC delivery path removes the need to store an Azure client secret in the repository.

GitHub Actions workflow
        |
        v
GitHub OIDC token request
        |
        v
Azure federated credential validation
        |
        v
Short-lived Azure access token
        |
        v
Terraform plan or controlled apply
        |
        v
Azure Resource Manager

The workflow identity is based on a trust relationship between GitHub Actions and Azure. GitHub issues a token for the workflow run; Azure validates the token against the configured federated credential; the workflow receives a short-lived Azure access token for the permitted operation.

The key engineering property is that the repository does not need to store a long-lived Azure deployment secret.

Delivery control chain¶

Git commit
    |
    v
GitHub Actions workflow
    |
    v
OIDC-authenticated Terraform plan
    |
    v
Human review / approval gate
    |
    v
Root-specific controlled apply
    |
    v
Azure Resource Manager
    |
    v
Validation output and evidence folder

The control chain is visible by design. A reviewer can follow a platform change from source control, through workflow execution, into a bounded Terraform root, and then into validation output or evidence.

Workflow implementation signals¶

The current workflow structure separates validation, root-specific planning, and controlled apply.

Workflow pattern	Implementation signal	Evidence path
CI matrix checks	The Release 2 Terraform CI workflow uses a matrix of Terraform roots for checks and validation.	Release 2 Terraform CI workflow
OIDC login	The workflow grants `id-token: write` and uses `azure/login@v2` with client ID, tenant ID, and subscription ID.	Release 2 Terraform CI workflow
Generic apply disabled	The generic multi-root apply workflow is disabled and points reviewers to dedicated root-specific workflows.	Disabled generic apply workflow
Root-specific apply	Platform networking has a dedicated workflow with explicit profile input and apply confirmation.	Platform networking hybrid apply workflow
Apply confirmation	Apply is skipped unless the workflow input confirms the reviewed plan should be applied.	Platform networking hybrid apply workflow

Controlled apply boundary¶

The controlled apply model is not only about authentication. It also records operator intent.

For roots that can affect expensive or sensitive infrastructure, the workflow uses explicit input and profile selection before running plan or apply. The platform networking workflow is the clearest example because it supports hybrid profiles for FortiGate, VPN Gateway, Azure Firewall, O3b AWS Cisco VPN, O4, O5, and service-chain validation.

This pattern creates three controls:

The selected profile is visible in the workflow run.
Terraform plan is generated with the selected root and profile flags.
Apply is skipped unless the operator explicitly confirms the reviewed plan should be applied.

Relationship to Terraform state boundaries¶

OIDC does not replace Terraform state discipline. It protects the authentication path into the state-controlled delivery model.

The complete Release 2 delivery model combines:

Split Terraform roots.
Remote state in Azure Storage.
Backend locking through blob leasing.
GitHub Actions OIDC authentication.
Plan-review-apply separation.
Root-specific workflows.
Active profile guardrails for optional or cost-sensitive resources.

This combination turns GitHub Actions from a task runner into a controlled infrastructure delivery plane.

Relationship to code traceability¶

OIDC provides the authenticated deployment identity. Code Traceability explains how a reviewer follows a change from source to evidence.

The audit chain is:

Git commit
    -> GitHub Actions workflow run
    -> OIDC-authenticated Terraform plan
    -> review or approval gate
    -> controlled Terraform apply
    -> evidence folder or validation output

The detailed traceability model remains in the Code Traceability engineering note.

Security properties¶

Property	How the design supports it
No long-lived Azure deployment secret in workflow code	GitHub Actions uses OIDC token exchange instead of storing a client secret in the repository.
Runtime identity is explicit	Azure receives a token issued for the workflow context and validates it through the federated credential trust.
Apply is deliberate	Root-specific apply workflows require explicit operator intent before mutation.
Review scope is bounded	Root selection and workflow design keep Terraform execution tied to the platform area being changed.
Generic apply is avoided	The generic multi-root apply workflow is disabled in favor of dedicated root-specific workflows.

Engineering significance¶

GitHub Actions OIDC shows five delivery engineering decisions:

Cloud deployment authentication avoids long-lived client secrets.
Terraform validation, planning, and apply are treated as separate lifecycle stages.
Root-specific workflows keep execution scope bounded.
Sensitive or cost-impacting roots require explicit profile selection and apply confirmation.
The delivery model is connected to the split-state architecture rather than operating as an isolated CI/CD script.

This is the Release 2 delivery control plane: Terraform state boundaries define what a workflow can affect; OIDC defines how the workflow authenticates; review and approval define when mutation is allowed.

Evidence map¶

Claim	Repository location	What to verify
OIDC is part of the Release 2 delivery model	Terraform state and pipeline map	Secretless authentication and GitHub Actions pipeline model
Terraform CI uses OIDC permissions and Azure login	Release 2 Terraform CI workflow	`permissions: id-token: write` and `azure/login@v2`
Generic multi-root apply is disabled	Disabled generic apply workflow	Workflow exits and directs users to dedicated root-specific workflows
Platform networking apply is root-specific and profile-aware	Platform networking hybrid apply workflow	Root working directory, profile input, selected Terraform flags, and `confirm_apply` gate
Plan-review-apply separation is documented	Terraform state and pipeline map	Pipeline flow and human review before apply
OIDC belongs to the split-state delivery model	Terraform State Boundaries	Root ownership, remote state, active profile guardrails, and bounded execution scope

Review takeaway¶

GitHub Actions OIDC shows that Release 2 delivery was designed around OIDC authentication, bounded root execution, explicit review, and controlled apply.

This mechanism lets Terraform operate as a platform delivery control plane rather than a local operator script.