Define a workflow triggered by schedule (cron syntax) for automatic promotion windows (e.g., every Tuesday at 10:00 UTC) and by workflow_dispatch for manual promotion.
Use a matrix strategy with a JSON array of environment objects (e.g., [{name: staging, cluster: stg}, {name: production, cluster: prod}]) to fan out deployment steps across environments in a controlled sequence.
Use needs to enforce ordering between matrix jobs so staging must succeed before production is attempted, creating a linear promotion chain within a single workflow run.
Gate production promotion with a GitHub environment protection rule (required reviewers or a deployment timer) on the production environment so the matrix job pauses for approval.
Pass the image tag or artifact version as a workflow input (for workflow_dispatch) or derive it from a previous release job that publishes the version to a workflow output.
Log the promotion results for each environment in the GitHub deployment API (create deployment + deployment status) to maintain an auditable promotion history per environment.
Known gotchas
The GitHub Actions matrix does not guarantee execution order for parallel jobs; use explicit needs relationships between matrix permutations or split environments into sequential jobs rather than a single matrix.
Environment protection rules apply per-environment by name; the environment name in the job definition must match the GitHub environment name exactly for the protection rule to trigger.
Cron-scheduled workflows do not run if no commits have been pushed to the default branch in the past 60 days; use a keep-alive workflow or switch to an external scheduler for truly time-driven release trains.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp