From 7eaa7fb3f93021c8b70c0181499d3839561a1987 Mon Sep 17 00:00:00 2001 From: Adam Moussa Date: Fri, 18 Sep 2026 11:22:50 -0400 Subject: [PATCH] docs(cd): document GitHub Environment branch and tag policies --- terraform/live/README.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/terraform/live/README.md b/terraform/live/README.md index ae77fcf..0c78f8f 100644 --- a/terraform/live/README.md +++ b/terraform/live/README.md @@ -137,11 +137,11 @@ restores the previous Elastic Beanstalk version label. Database migrations already applied by the failed bundle are not reverted. Deploy parameters are read from `/shoc-backend//deploy/*` SSM parameters this module writes. -Merge to `main` deploys **dev** unless the push is terraform-only. Staging and -prod are cut from **Actions → Release** (`environment`, `bump`, `message`). -That workflow waits for CI, tags `vX.Y.Z-staging` or `vX.Y.Z` from main HEAD -with `GITHUB_TOKEN`, then calls deploy. Prod waits on GitHub Environment -reviewers; AWS steps stay skipped until `PROD_APP_CD_ENABLED` is true. +Merge to `main` deploys **dev** unless the push is terraform-only. Staging is +cut from **Actions → Release** (`environment`, `bump`, `message`). That +workflow waits for CI, tags `vX.Y.Z-staging` from main HEAD with +`GITHUB_TOKEN`, then calls deploy. Do not cut prod yet; leave +`PROD_APP_CD_ENABLED` unset and do not create the `prod` GitHub Environment. Staging remains `adoption_complete=false` with a pinned API CNAME until its import apply is proven. @@ -160,13 +160,32 @@ on that leftover path only. ### Credentials Store `DEPLOY_ROLE_ARN` as a GitHub Environment **variable** (`dev`, -`staging`, later `prod`). OIDC trust is +`staging`). OIDC trust is `repo:Sea-Haven-Industries/shoc-backend:environment:` plus `job_workflow_ref` for `.github/workflows/deploy.yaml` at `refs/heads/main` and `refs/tags/v*`. Adding another deploy workflow is a cross-family IAM change. After cutover, drop `TF_API_TOKEN` from GitHub Environments. The new CD path does not use it. +GitHub Environment deployment branch and tag policies are repository +settings, not this diff. Update them before the first merge to `main` and +the first staging cut. The policy matches `GITHUB_REF` of the workflow run. +Branch patterns never match tag refs; adding `v*` as a branch pattern fails +the same way as an empty allowlist. + +1. `dev` — allow branch `main`. Keep `dev` allowed while leftover + `.github/workflows/deploy.yml` still deploys from that branch. +2. `staging` — add a **tag-type** policy matching `v*.*.*-staging` for + `deploy-tag.yaml`. Allow branch `main` because Actions → Release is + `workflow_dispatch` on `main` and then calls `deploy.yaml` + (`GITHUB_TOKEN` tag pushes do not start `deploy-tag.yaml`). Keep + `staging` allowed while leftover `deploy.yml` still deploys from that + branch. + +Do not create the `prod` environment yet. Leave `PROD_APP_CD_ENABLED` +unset. Do not run Actions → Release with `environment=prod`; the first +prod dispatch would auto-create an unprotected environment. + ## Pinned live identities - Dev: workspace `shoc-backend-dev`; EB environment `shoc-backend-dev`