feat: environment protection rules — required reviewers for sensitive workflow jobs

[ms280690]

Context

Track: B — Org/infrastructure governance
Pillar: 3 — Modern Secret Management & Identity Federation
Parent: #27
Cross-references: #27 (OIDC trust policy scoped to environment), #29 (org rulesets)

Why environment protection rules

SHA pinning and OIDC credentials (#27) control what a workflow can do. Environment protection rules control who can trigger it and when. Without an approval gate, any workflow with access to production credentials can run the moment a PR merges — no human in the loop.

GitHub Environments provide the closest equivalent to MFA/2FA for sensitive workflow jobs: a named reviewer (person or team) must explicitly approve before the job starts. No job steps execute — and no OIDC token is exchanged — until approval is granted.

This is particularly relevant for:

Workflow type	Risk without gate
tofu apply / terraform apply	Live infrastructure changes, potentially destructive
Production deploys	Service disruption, data exposure
Integration tests against live environments	Unintended mutations to shared state
Secret rotation workflows	Credential invalidation
Release/package publish	Supply chain — published artefacts are immutable

Implementation pattern

1. Define environments in GitHub UI

For each protected environment (production, staging):

• Required reviewers: add the sparkgeo/platform team (or named individuals)
• Wait timer: 0 min for staging, optional 5 min for production (change-freeze buffer)
• Deployment branches: restrict to main only for production; main + release/** for staging
• Prevent self-review: enable — the person who merged the PR cannot also approve the deploy

2. Add environment: key to sensitive jobs

jobs:
  apply:
    environment: production          # job pauses here until a reviewer approves
    permissions:
      id-token: write                # OIDC token only issued after approval
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@...
        with:
          role-to-assume: ${{ vars.AWS_ROLE_ARN }}

The OIDC trust policy in AWS (added in #27) should also require environment: production in the token claims:

{
  "StringEquals": {
    "token.actions.githubusercontent.com:environment": "production"
  }
}

This means even if someone bypasses the approval gate, the OIDC token will not be issued for a production role unless the job is running in the production environment.

3. Reusable workflow pattern for this library

Add a documented example workflow to this repo showing the environment gate pattern, so consuming repos have a reference implementation:

# .github/workflows/deploy-with-gate.yml
# Reusable: caller passes environment name; caller's repo must have that environment configured.
on:
  workflow_call:
    inputs:
      environment:
        description: 'Target environment (production | staging)'
        required: true
        type: string

Relationship to existing tooling

• OIDC trust policies (feat: OIDC federation and secret management #27) and environment gates are defence-in-depth layers — either one alone is insufficient
• Allstar (see companion sub-issue) can enforce that required environments exist on repos via the branch_protection policy
• Org rulesets (feat: enterprise governance, rulesets, and observability #29) can make the environment-gated deploy workflow a required check org-wide

Acceptance criteria

• production and staging environments created in sparkgeo/github-actions repo settings
• Required reviewers configured on both environments (sparkgeo/platform team or named individuals)
• Deployment branch restrictions set: main only for production
• OIDC trust policies updated to require environment claim (cross-ref feat: OIDC federation and secret management #27)
• Reference reusable workflow deploy-with-gate.yml added to this repo as a documented example
• CONTRIBUTING.md updated: add environment protection rule requirement to sensitive-workflow authoring checklist
• Guidance documented: how consuming repos should create and configure their own environments