Branching and Releases¶
How code gets from a laptop to production in every CookieHub repository.
Decided 21 September 2026 (IS-87), replacing a three-long-lived-branch setup. If you are new here, this is the page to read first; the per-service mechanics are in Deployments.
Required access¶
Reading this page needs nothing. Acting on it needs:
| To do this | You need |
|---|---|
Merge to main |
Write access to the repo, plus an approving review from someone else |
Push or force-push stage |
Write access to the repo |
Cut a v* tag / publish a release |
Write access to the repo. The "Protect release tags" rulesets block deleting, moving or force-updating a v* tag once it exists; they do not restrict who may create one |
| Approve a production deployment | Membership of the repo's production environment reviewers — one approval from the environment's required reviewers, never the person who cut the release. Today that is Ástþór or Benedikt; atrax and atrax-api add a third reviewer |
| Change a trust policy, deploy role or task definition | An Infrastructure & Security issue and an infra pull request that Ástþór reviews, then a terraform apply by Ástþór — nobody else applies, and never an assistant |
| Inspect a production deploy's approval record | Repo → Settings → Environments → production → deployment history, or the run's summary |
No AWS credentials, SSM tunnel or VPN access is needed for a normal release: the deploy workflow
assumes its role through GitHub's OIDC provider and no long-lived key is stored anywhere. That covers AWS only, not
npm or WordPress.org credentials. The exceptions are the repos that publish to a package registry rather than deploy a service, where there is no gate yet,
and docs-internal and infra, which have no release — see the status table at the bottom.
The model¶
Two branches and a tag.
| Ref | What it is | Who may write to it |
|---|---|---|
main |
Latest stable. Always releasable, because a tag can be cut from it at any moment. | Reviewed pull requests only |
stage |
Auto-deploys to the stage environment. Disposable. | Anyone, any time, including force-push |
a v* tag on main |
Auto-deploys to production, behind a required-reviewer gate | Whoever cuts releases |
flowchart LR
F[feature branch] -->|"merge freely, no review, force-push OK"| S[stage]
F -->|"reviewed PR"| M[main]
M -->|"cut a v* tag"| T[tag]
T -->|"approved by a reviewer"| P[production]
S --> SE[stage environment]
M -.->|"never"| S
S -.->|"never"| M
Why a tag and not a prod branch¶
A branch is a parallel line of history, so it drifts — and it did. A tag is a point in main's history, so it cannot. Two consequences worth knowing:
- Rollback can be redeploying the previous tag instead of writing and reviewing a revert, within limits: see Rolling back for what that does and does not restore.
- There is no "is prod up to date with main?" question. Production is a commit on main, by construction, and the release workflow refuses any tag that is not.
The rules that make it hold¶
A feature branch has two destinations, and stage is not on the path to main.
Merge to stage freely to test something — no review, force-push allowed. Merge to main by
reviewed PR, from the feature branch. Nothing reaches main by way of stage.
This is the rule the whole model rests on. If work starts flowing to main through stage, stage
becomes a second long-lived branch with its own history and we have rebuilt the problem we removed.
Most repos enforce it in CI with a source-branch-guard.yml workflow that fails any pull request
whose head branch is stage, and that check is required on main.
Stage is throwaway. Drift is accepted and never reconciled. Force-push it whenever you need the
environment to hold something specific. Reset it from main when it is in the way — not on a
schedule, and not because it looks strange. Breaking stage is not an incident; see
Stage is a developer environment below.
Rebase your feature branch on current main before merging it to stage. Otherwise a green
stage run tells you only that your work coexists with whatever else happens to be sitting on stage,
including work that will never land.
Tags are cut from main only, and that is enforced in the release workflow rather than by
convention. See The ancestor-of-main guard.
Cutting a release¶
A release is a vMAJOR.MINOR.PATCH tag on main, published as a GitHub Release and deployed by the repo's
production workflow behind the production environment gate. Linear records the same release in the repo's
release pipeline. The two must tell the same story, and this is the order that keeps them aligned: prepare in
Linear and git, cut on GitHub, close out in Linear after the deploy.
The pipelines, by repo:
| Repo | Linear release pipeline |
|---|---|
widget |
CookieHub CMP |
core |
Legacy Dash |
core-api |
Core API |
core-portal |
React Dashboard |
edge-api |
Edge API |
vault-api |
Vault API |
vault-ingest |
Vault Ingest |
atrax |
Atrax |
atrax-api |
Atrax API |
admin |
Admin |
docs |
Docs |
dsar |
DSAR |
| mobile SDK | Mobile SDK |
react-cookiehub |
react-cookiehub |
nuxt-cookiehub |
nuxt-cookiehub |
cookiechecker and wordpress-plugin have no pipeline yet: the workspace is at its pipeline limit. Their releases
still get a release issue and a written note (below); attach them to a pipeline when one exists.
Before the cut¶
Most of this is continuous, not release-day work.
- A Planned release exists in the repo's pipeline (create it if none exists; several pipelines have no releases yet), for the next version, with every merged issue attached. The PR title carries the issue id, so the GitHub integration links the PR; attaching the issue to the release is a manual step when the PR merges. A merged PR with no issue is a gap: file the issue, or name the PR in the release note. Never leave it invisible.
- Create the release issue once the release is decided, from the Linear template "Release" (it exists on the
Product & Engineering team): title
Release <repo> <version>, assigned to whoever is cutting, attached to the pipeline release. One per cut, always, even when it is three ticked boxes: it is the human record the gate's approval points at. Add sub-issues only where a step is real work (the version-bump PR, a public changelog PR, customer communication, post-release verification, repo-specific follow-ups such as the widget's domain republish). - Version bump, where the repo has a version.
package.jsonrepos bump onmainfirst (chore(release): vX.Y.Z, reviewed like any PR), and the tag then goes on that merge commit. The widget follows the CH-698 scheme: the production version comes from the tag (release.ymlextracts it), and stage readsSTAGE_VERSION, so those are the version inputs the widget bumps.corehas no version file: the tag is the version (CH-831). Do not edit a version by hand outside this step.
The bump PR carries its own sub-issue id (or no Linear id), never the release issue's id. Otherwise the GitHub
integration closes the release issue when the bump merges, before the cut.
4. Create a release note in the repo's pipeline (Release notes, then New), covering this release. It is a separate
object attached to the release, not the release's description field. Write customer-facing "What's new", then
"Internal", then "Migrations" where any run, and use its text as --notes-file. The GitHub Release body is the
same text. The public change log (docs repo)
follows its own rule when the release is customer-facing; core (Legacy Dash)
releases have never had public notes and stay out of it.
The cut¶
# on main, with the version bump already merged
gh release create v1.4.0 --repo cookiehub-com/<repo> --target <sha of main> \
--title v1.4.0 --notes-file release-note.md
--notes-file takes the text of the Linear release note. --generate-notes remains as the fallback for a
trivial internal cut, where the note is a list of merged PRs and nothing more; it is not the default, because the
generated list is not the record of what shipped.
Publishing the release fires the production deploy workflow, which:
- Waits for a required reviewer to approve the deployment.
- Checks out the tag.
- Verifies the tag is an ancestor of
mainand fails if it is not. - Builds the image, pushes it (tagged by commit SHA,
:latestand:<tag>;edge-apiproduction pushes:<tag>and:latestand no:<sha>), deploys it, and waits for the service to settle. Where the repo is pinned (see the status table) the deploy registers a new ECS task-definition revision pinned to that SHA;coreupdates its server in place over SSM. - Posts a card to the prod deploys Teams channel.
Once the card says the deploy succeeded, run the post-deploy smoke checklist for the service. It is the Release issue's post-release verification, and its failures are what send you to Rolling back.
Step 1 is the change-approval record. GitHub stores the approver, the timestamp and the exact SHA in the
environment's deployment history, which is what Sprinto and a SOC 2 auditor collect. It replaces the old "the prod
branch requires reviews" rule. The reviewer is another member of the repo's production environment reviewers, never
the cutter.
Approvers should know that the ancestor guard has not run yet when they approve: the gate sits on the job that runs
the guard (or ahead of it), so approving does not certify that the tag is on main. The exception is admin, whose guard
and image push to the production ECR run in build-push before the gate. Some repos also run an ungated job first
(docs and cookiechecker a quality job, widget a build job that uploads the dist zip).
Also at the cut: move the Linear release to In Progress, recording the tag commit and the cut time.
After the deploy¶
- Deploy succeeded: Linear release to Released, with the deploy end time; the release issue to Done; and the cutter creates the next Planned release in the pipeline straight away (rollover carries unfinished issues).
- Deploy failed or was rolled back: the Linear release stays In Progress with a comment saying what happened, or goes to Canceled with the reason. The tag is never reused; the fix is the next version.
Rules that fall out of this¶
- Nothing deploys to production except a published GitHub Release on a
v*tag. - A published version is never replaced (CH-698; SDLC Procedure 4.3.1). A fix is a new patch, never new bytes under an existing tag.
- Soak fixes are builds, not releases: a widget
2.10.1or2.10.2is a build inside release 2.10, with no new Linear release and one dated line appended to the release note and the change log. - The release note is the record of what shipped. If it is not in the note, it did not ship.
Versioning¶
vMAJOR.MINOR.PATCH. Where the repo carries a version file, it tracks the repo's package.json version by convention — no
workflow reads the file or compares it to the tag, so keeping them in step is part of the cut. Bump the version on main
first, then tag the merge commit that carries the bump. core has no version file: the tag is the version (CH-831).
Never pre-create a tag for a planned release. Releases get renumbered when scope moves, and git
tags are effectively immutable — tag at deploy time. Never re-cut or move an existing tag; the
tag rulesets block it, and in widget a moved tag would silently re-point a published artifact.
Immutable builds: release and build numbering¶
Decided 24 September 2026 (CH-698). This is widget-specific — it splits the widget's version
string into a release and a build within it. Other repos' vMAJOR.MINOR.PATCH tags, above, are
unaffected.
The rule¶
A published build is never replaced. A bug found in something already served becomes a new
build, never new bytes under an existing name. No RC suffixes — the version string is unchanged and
still matches ^\d+\.\d+\.\d+$.
Release vs. build¶
major.minor is the release; patch is the build within it. Each build is a distinct immutable
artifact with its own folder on the CDN.
Example: release 2.10. First build 2.10.0. A fix found during soak is 2.10.1, then
2.10.2 — not a new release, not an RC, a new build of the same release.
Customers upgrade to a release, not a build. The changelog is written once per release ("2.10, US
and GPP changes and Canadian province support" covers every build under it); a one-line soak fix
is not presented as a release. See
Change log and release notes below for the exact shape.
Every release takes a minor bump by construction now — the old scheme let a significant change ship
as e.g. 2.8.4 when it should have been 2.9.x; minors are cheap.
Bridge: TCF v2.4 ships as 2.9.3 on 25 Sep 2026, as already planned; the new scheme starts at
2.10. If 2.9.3 needs a soak fix, it is 2.9.4 — immutability applies from now — and its release
notes read as a fix to the TCF release, pointing back to the 2.9.3 changelog.
Change log and release notes¶
Decided 29 September 2026 (CH-698 follow-up, D7). From release 2.10, the public change log
(docs repo, content/getting-started/change-log.mdx) gets one entry per release, not per
build: ## 2.10 carries the Date (the first build's publish date), Tags, narrative and bullets
directly underneath it — no ### 2.10.0 heading. A soak build (2.10.1, 2.10.2, …) appends a
dated line under the release's bullets, e.g. "Updated 3 October 2026: fixed …", and gets no
heading, no Linear release and no release-notes page of its own. The per-release notes page (the
/getting-started/release-notes/cookiehub-2.9 pattern) is likewise one page per release.
2.9.x entries keep their existing per-build headings; nothing about them changes now. The one
exception is a 2.9.4 bridge fix, if 2.9.3 ever needs one (see above), which is a ### 2.9.4 under
## 2.9 whose text says it is a fix to 2.9.3 and points back at the 2.9.3 entry — a one-off, not
the new pattern.
(The GitHub Release body, above, is the Linear release note and is a separate thing from this public change log.)
What the customer sees¶
Decided 24 September 2026, now built: domains pin to a release and follow its newest build, so a build bump inside a release reaches them with no separate action; the soak uses
the existing stable flag at release level (published but not yet stable → only domains that
select it explicitly are on it; marking the release stable moves everyone over). No new channel
column, no separate RC row.
Domains still pin to a single widget_versions build row. From release 2.10 onward (the
WIDGET_RELEASES_FOLLOW_MIN_RELEASE floor, default 2.10) the scheduled widget:follow-release sweep
moves every active (non-suspended) domain on an older build of its release to the newest build and republishes it when its
settings are current, so a build bump reaches the release's domains within minutes with no customer
action (CH-836). It runs every five minutes on prod and stage; settings saved but not yet published
are never published for the customer, the domain is only repointed to the new build. widget:release-flag <release> …
--upgrade-now runs the sweep straight after flipping the flags, without waiting for the next tick. It does not bypass the floor: for a release below 2.10 the sweep
refuses (the flags are still written), so use widget:follow-release <release> --force by hand.
Below the floor the old build-by-build behaviour stays: a 2.9.2 domain is still offered 2.9.3 and
moved by widget:upgrade, which is what keeps a one-off 2.9.4 reachable. An operator can sweep an
older release by hand with widget:follow-release <release> --force (add --dry-run first).
The customer picker (upgrade card and modal in both dashboards; the bulk list in the Laravel dashboard) offers releases, not builds: "Upgrade to CookieHub 2.11" (CH-839). From the floor up, a build of the domain's own release is never offered. The build stays visible in the "Version:" line, the admin domain select, the compiled bundle head and the CSS URL. A visible release that is not yet stable is still shown as RC.
On releases at or above the floor, widget:upgrade never moves a domain onto a release flagged
autoupdate=0; a customer may still pick such a release by hand.
None of this is on prod yet: it ships with the next core release tag, and until then prod runs the
pre-2.10 behaviour.
Widget settings lock¶
When the lock is on, the Laravel dashboard refuses settings edits for a domain pinned to widget
2.8.4 or older (widget_versions.id ≤ 213, the build that carried the Google Consent Mode changes),
so staying there costs something (CH-523). Upgrading the widget is the one action left open, and it
carries unpublished changes along as a draft. The dashboard shows a banner with an upgrade link, and
it also refuses a history restore onto a locked version. No customer notice went out ahead of it
(decided 12 October 2026): the banner and the in-place upgrade are the notice.
State: switched on in production on 20 October 2026 at 13:35. The exempt list is empty. Off on stage for now.
Env var (core .env) |
Default | Meaning |
|---|---|---|
WIDGET_SETTINGS_LOCK_ENABLED |
false |
Turns the lock on. |
WIDGET_SETTINGS_LOCK_EXEMPT_DOMAIN_IDS |
empty | Comma-separated domain ids that stay editable on an old widget, for domains known to be genuinely unable to upgrade. |
The version cut-off (max_widget_version_id) is a product decision. It lives in
config/services.php, not in the environment, so changing it is a code change and a release.
The lock is enforced only where the dashboard alone writes: its views, and the portal-token
endpoints nothing else calls. Domain::updateSettings(), the Client API, the crons, the bulk
upgrade command and the plugins are never locked, because a wrong gate on a shared write path would
block the whole fleet rather than one page. The lock also fails open: when it is switched off, the
domain is exempt, the version is unknown, or there is no stable build to upgrade to, the domain
stays editable. Code: App\Support\WidgetSettingsLock.
Exempting a domain, or switching the lock off. Edit the variable in the box's .env
(/home/cookiehub/core/.env, as the cookiehub user), then run php artisan config:clear. Never
run config:cache. No deploy is needed. On stage, use the recipe in
Stage operations. Both variables are in
core's _setup/env/prod and _setup/env/stage, so a rebuilt box keeps its setting. A domain id added
to a live box must also be added to the matching _setup/env file, or a rebuild drops the
exemption.
The artifact half¶
Tags are immutable — the v* tag ruleset blocks deletion and non-fast-forward —
and, since 29 September 2026 (CH-698), the artifact side is too.
Ids are banded per release. The widget_versions id is not derived from the version, and
roughly ten behaviour gates in core compare on it, so a newer release must always sit above an
older one. The first build of a new release takes the next multiple of 50 above the highest id,
deleted rows included; later builds of the same release take the next id inside that band. So the
cutter need not care about order: a back-branch build is safe to register. For example, on prod
today, with 2.9.3 at 253, 2.10.0 lands at 300 and a later 2.9.4 at 254, below 2.10's band.
What a 409 from POST /api/widget/v1/releases means:
- The version is already registered from a different commit, or with no recorded commit (everything
registered before
source_shawas recorded,2.9.3included). The build is immutable — cut the next build number. - The release's id band is full (the 51st build), or a legacy release (such as 2.7/2.8) has a next id that collides with another release. Cut a new release.
- The version's row is soft-deleted. Restore it first. (A same-commit re-run of a soft-deleted version gets a 200 that does nothing, so check the version is actually live.)
A same-commit re-run of the release workflow is a 200 no-op and is the only legitimate retry. The
workflow fails the job on any 409 and prints the body. It also refuses on its own side, before
uploading, if the S3 prefix already holds a different commit's build (manifest.json) or a build
with no manifest (published before the guard, or a publish interrupted before the manifest was
written). Neither is retryable; cut the next build.
Stage exception. Stage re-pushes the same version on every push, and core allows that only with
WIDGET_RELEASES_ALLOW_REPLACE=true in the stage box's .env (hand-edited over SSM, then
php artisan config:clear; _setup/env/stage carries it for a rebuilt box). It is off by default,
and prod never sets it.
Flipping a release's flags. php artisan widget:release-flag 2.10 --stable=1 --autoupdate=1 is
how a release is marked stable; run it with --dry-run first. Every non-deleted build of the
release flips together, and a new build inherits its release's flags when registered. Boolean values
are 0/1/true/false/yes/no; empty or bare ones (--stable, --stable=) are refused.
Enforcement¶
Both halves are in place:
release.yml(CH-835) refuses to upload over an S3 prefix that already holds a different commit's build or a build with no manifest, and no longer uses--clobber.ReleaseController(CH-834) refuses to re-register an existing version from a different commit, or a soft-deleted one, with 409 instead of upserting.
Policy basis¶
- SDLC Procedure 4.3.1 — "Previous version(s) of the software shall be retained as a contingency measure in case a rollback is required."
- Operations Security Procedure 3.1.1 — software "should be version controlled i.e. the latest version of our software as well as any previous version of our software are readily available."
Overwriting a published version's artifacts destroys the artifact that was running in production — the thing both lines exist to preserve.
An urgent fix does not get a parallel fast path: it is simply the next build, and the existing break-glass wording already covers the review side.
Rolling back¶
What "rollback" means depends on the repo. Be precise about this under pressure.
An ECS service (core-api, edge-api, vault-api, atrax, atrax-api, vault-ingest, admin)¶
Every one of these rollbacks currently rebuilds. Be clear about that before you rely on it:
- Only
adminhas aworkflow_dispatchtrigger on its production workflow, sogh workflow run deploy.yml --repo cookiehub-com/admin --ref v1.3.0works foradminand for nothing else. For the others, the production workflow isdeploy-prod.ymlonrelease: publishedonly, and the path is re-running the earlier release's deploy run from the Actions UI (gh run list --workflow deploy-prod.yml, then re-run it). It still needs a reviewer approval, like any production deploy. - A re-run works for 30 days after the original run. GitHub does not allow re-running an older workflow run. After
that the paths are a new patch release cut from a revert on
main(it goes through the gate like any release), or, for ECS services, the task-definition revision route below (aws ecs update-service --task-definition <family>:<older revision>), which is break-glass until IS-135 proves it. - A re-run rebuilds the image from source and pushes
:<sha>again. ECR repositories are mutable, so the old:<sha>tag is overwritten, and where the base image is not digest-pinned the new bytes may differ from what ran before. That is a redeploy of the same commit, not of the same image. - Where the workflow is SHA-pinned (
admin,vault-api,core-api,atrax,atrax-api,vault-ingest) the re-run does at least register a new task-definition revision pinned to that SHA.edge-apiproduction is not pinned: it pushes:<tag>and:latestand runsupdate-service --force-new-deploymentagainst the existing revision, so the running image tracks:latest.
The one rollback that really restores a known image is to point the service at an earlier task-definition revision, which still references the image that revision was registered with:
aws ecs list-task-definitions --family-prefix <family> --sort DESC --max-items 5 --region <region>
aws ecs update-service --cluster <cluster> --service <service> \
--task-definition <family>:<older revision> --region <region>
This needs production AWS access (no approval gate, no audit record beyond CloudTrail), so it is the break-glass route: use it when waiting for a reviewer is worse than the risk, and follow Break-glass afterwards. It is only as good as the image behind the revision; see below. The services' families and clusters are in Deployments.
State of the target
The target is that rolling back means redeploying an immutable, already-built image. IS-102 pinned task
definitions to an image tag where it could, and that part is done; it is why the SHA-pinned services above
register a revision per release. What is left is tracked in IS-135: edge-api production (and core-api stage)
still deploy against :latest, every ECR repository is mutable so a re-run overwrites :<sha>, and a rollback
without a rebuild has not yet been proven end to end on a real service. Until IS-135 closes, treat a workflow
re-run as a rebuild.
core (the Laravel monolith)¶
A tag rollback re-checks-out the old tree, re-installs dependencies, rebuilds the dashboard assets and clears caches. It restores core's PHP code and dashboard assets, and nothing else. It does not revert:
- the database schema — the deploy runs
php artisan migrate --forceforward only, and nothing ever callsmigrate:rollback; - per-domain compiled widget bundles under
public/c2,public/cc,public/dev,public/cdn; public/c2/css/<version>.cssor the CDN objects the app writes when a widget release is registered.
So rolling core back leaves old code meeting a newer schema. Decide deliberately whether that is
better or worse than the bug you are rolling back.
The rollback step: re-run the earlier release's deploy-prod.yml run within 30 days of that run, and approve it again
at the gate; after 30 days, cut a new patch release (a revert on main).
widget¶
Widget has no deploy-level rollback, by design — and that is better than having one. Customer
domains are pinned to a widget_version_id, not to "latest", so an older, already-registered
version's CDN artifacts are untouched by a rollback — see
Immutable builds: a published version's files are
never re-uploaded.
Rolling widget back in production means repointing domains to the older widget_version_id and
republishing their per-domain bundles, not re-running a workflow or re-registering the version.
docs and cookiechecker (Vercel)¶
Re-run the previous release's deploy run from the Actions UI (within 30 days of that run; after that cut a new patch
release from a revert on main), or promote the previous deployment in the Vercel dashboard. There is no schema and no artifact registry to reason about.
Both repos disable Vercel's own Git builds via git.deploymentEnabled: false in vercel.json, so
the Actions workflow is the only path to production. That setting only bites on the project's
configured production branch — while docs still had prod set as its production branch in
Vercel, the flag sat on main doing nothing. If Vercel starts building production on pushes again,
check which branch the project calls production before suspecting the flag.
Hotfixes¶
Branch from main, open a reviewed PR into main, tag, approve, deploy. Stage is not involved.
This is more steps than the old hotfix/* → prod path, and that is deliberate — a hotfix is still
a production change and still needs the approval record. The cost is real for services where a bad
deploy is a full outage: a reviewer who is asleep becomes the new time-to-recovery.
Break-glass¶
It should be possible, but not easy. There is no standing bypass. Every production
environment is created with can_admins_bypass: false, so using break-glass means an admin
deliberately flipping that boolean — which the org audit log records. Possible, but not something
anyone does by accident or in a hurry.
Operations Security Procedure 3.1.4 permits an urgent change to skip peer review only if it is peer-reviewed after the fact. So the bypass is not finished when the deploy lands: it is finished when the other approver has reviewed it and recorded that on the incident's Linear issue.
bypass_actors is a ruleset concept, not an environment one
Branch and tag rulesets carry a bypass_actors list, so you can name individuals there.
Deployment environments do not — they expose only the can_admins_bypass boolean. Do not
plan a break-glass path around naming an actor on an environment; there is nowhere to put one.
Self-approval is blocked, not tolerated¶
Every production environment is created with prevent_self_review: true, so the person who
cuts a release cannot approve its deployment. Operation Security Policy 4.1 requires that
requestor, approver and implementer are not the same user, and this is what enforces it.
With a pool of two reviewers that means the other reviewer in the environment approves (atrax and
atrax-api have a third reviewer) — and that if the other reviewer is unavailable, the release waits. That is the intended cost. The reviewed PR
into main is a second, independent record of the same separation.
What a production deploy workflow must include¶
Copy these from a repo that already has them rather than writing them fresh.
admin/deploy/README.md is the best-written reference; edge-api has the canonical Teams steps.
The ancestor-of-main guard¶
Nothing in on: release: published or on: push: tags: verifies that a tag is reachable from
main — a release's targetCommitish records only where the UI created the tag, not what the tag
points at. Only an explicit step checks it. Note fetch-depth: 0; the default shallow checkout
makes merge-base misbehave silently.
- uses: actions/checkout@v4
with:
ref: ${{ github.event.release.tag_name }}
fetch-depth: 0
- name: Verify the release tag is on main
run: |
set -euo pipefail
git fetch --no-tags origin main
if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
echo "::error::Tag ($GITHUB_SHA) is not an ancestor of main."
exit 1
fi
The approval gate¶
jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: production
url: https://<the service's prod URL>
The production environment carries the required reviewers and can_admins_bypass: false, and its
deployment branch policy is restricted to the v* tag pattern.
Adding environment: changes the OIDC subject
A job that declares an environment presents
repo:cookiehub-com/<repo>:environment:production instead of
repo:cookiehub-com/<repo>:ref:refs/tags/v1.2.3. Our prod deploy roles trust the ref form,
so adding the gate without widening the trust policy breaks production deploys immediately at
AssumeRoleWithWebIdentity. The Terraform change lands first. Tracked in IS-103.
The SHA-pinned deploy¶
Push :<sha>, :latest and :<tag>, but feed only the commit SHA to the task definition, so
:latest is never what runs:
- name: Fetch the current task definition
run: aws ecs describe-task-definition --task-definition "$ECS_TASK_FAMILY" \
--query taskDefinition > task-definition.json
- uses: aws-actions/amazon-ecs-render-task-definition@v1
with:
task-definition: task-definition.json
container-name: ${{ env.ECS_CONTAINER_NAME }}
image: ${{ needs.build-push.outputs.image }} # <ecr_url>:<git sha>
- uses: aws-actions/amazon-ecs-deploy-task-definition@v2
with:
wait-for-service-stability: true
On the Terraform side the service tracks the newest ACTIVE task-definition revision using the
max() pattern, not ignore_changes, so a later terraform apply does not roll a deploy back
while still rolling task-shape changes out immediately.
Tag protection¶
A ruleset targeting refs/tags/v* blocks deletion and non-fast-forward, so a released tag cannot be
moved or removed after the fact.
Teams notifications¶
Two steps after the deploy — if: success() posts a ✅ Adaptive Card, if: failure() a ❌ one.
Copy the bash body verbatim; only the webhook secret and the card's fields change. For a multi-job
workflow use a separate notify job with needs: [...], if: always() and conditions on
needs.*.result, or a failure in an early job means the notify never runs.
Where did my stage deploy go?¶
Stage deploys are chained off CI with workflow_run, and a workflow_run-triggered run always
reports head_branch=main, whatever branch actually triggered it. Two consequences:
- The stage deploy does not appear when you filter the Actions UI by
stage. It is filed undermain. It has not failed to fire; you are looking in the wrong place. - That behaviour is load-bearing — do not "fix" it. The stage deploy roles trust
ref:refs/heads/main, and only aworkflow_runjob presents that subject. Rewriting the stage deploy ason: push: branches: [stage]would presentref:refs/heads/stageand fail the assume-role.
The same applies to workflow_dispatch if one is ever added as an escape hatch: it presents
ref:refs/heads/<the ref you dispatch on>, so it works dispatched on main and fails on stage.
Stage is a developer environment¶
Stage has no real customers on it, ever. It is used by the dev team to test features.
Temporarily breaking stage while making changes is perfectly acceptable and is never a reason to stop, slow down or ask permission. Note that a change might break stage and how to recover, then keep going. Production is the opposite: production breakage is a real concern and does gate work.
Per-repo status¶
As of 2 October 2026 (IS-87). Every repo with a service in production now has a gated, release-triggered production
deploy; the rows below record the exceptions. "Gate" means the repo's lowercase production GitHub environment with
required reviewers, prevent_self_review: true and can_admins_bypass: false; the reviewers are the environment's
required reviewers.
| Repo | Production deploys from | Approval gate | Notes |
|---|---|---|---|
core |
v* release on main |
gated | SSM deploy to the production EC2 box; no prod branch. The tag is the version (CH-831) |
core-api |
v* release |
gated | Pre-production: main needs 0 approvals (IS-87 D7) and the production service is held at 0 tasks until go-live. SHA-pinned workflow |
core-portal |
no production yet | n/a | Pre-production: main needs 0 approvals (IS-87 D7); no production environment yet |
widget |
v* release |
gated | release.yml; Stage and Preview environments stay ungated. See Immutable builds |
admin |
v* release |
gated | SHA-pinned. Stage deploys on push to main and there is no stage branch: legacy, not a decision (IS-133) |
edge-api |
v* release |
gated | Ancestor guard and gate; not SHA-pinned, the service runs :latest (IS-135) |
vault-api |
v* release |
gated | IS-89. The full model: ancestor guard, gate, SHA-pinned deploy |
vault-ingest |
v* release |
gated | Seven ECS services deployed from one image, each registered as a SHA-pinned revision |
atrax |
v* release |
gated | Three required reviewers on the environment. Still has a prod branch to retire (IS-129) |
atrax-api |
v* release |
gated | Three required reviewers on the environment |
docs |
v* release on main |
gated | Migrated 23 Sep 2026. No prod branch, and no more twin PRs |
cookiechecker |
v* release on main |
gated | Migrated 23 Sep 2026. No prod branch |
docs-internal |
push to main |
none | Deliberate exception: an internal site deployed to Cloudflare Pages on every push to main, with no release |
infra |
no release | n/a | Nothing deploys from the repo. Ástþór applies Terraform from an Infrastructure & Security issue and a reviewed PR |
react-cookiehub, nuxt-cookiehub |
manual npm publish |
none | No publish workflow exists; no gate yet (IS-134) |
wordpress-plugin |
publishes to WordPress.org SVN on any tag push | none | Trigger is tags: '*', not v*, with an on-main guard. No gate yet (IS-134) |
cmp |
no release path | n/a | Repo is on ice; no release path (IS-134). Vercel-created, ungated Production environments still exist on the repo (last deploy Feb 2026) |
sandbox |
Vercel Git integration | n/a | Out of scope — internal test harness |
Environment names case-fold, and an ungated Production silently swallows the gate
GitHub matches environment names case-insensitively and cannot rename an environment. A job
declaring environment: production in a repo that already has a Vercel-created capital-P
Production will bind to that object. The run then records the environment as production
and looks gated in the UI — while actually executing against Production's empty
protection_rules.
This is not hypothetical: docs shipped v1.0.0 this way on 23 Sep 2026. The workflow ran end
to end, the ancestor guard passed, the deploy was legitimate — and no approval was ever
requested, so the control produced no record.
Before wiring a repo up, list its environments and delete any stray capital-P one. Deleting an
environment does not destroy the deployment history attached to it — that was tested
directly. widget used to carry an ungated capital-P Production; it is gone, and only Stage and Preview
remain ungated.
docs: the twin-PR convention is retired
Public documentation used to ship as two PRs — one into main and a squashed twin into
prod — because prod was what Vercel built. There is no prod branch any more, so a change
to docs.cookiehub.com is now one PR into main, and it goes live when someone cuts a v*
release. Any …-prod twin branches still on the remote are leftovers (IS-100).
Related¶
- Incident Response — severity, first ten minutes, rollback, break-glass and the review
- Deployments — per-service mechanics, names and status commands
- Post-deploy smoke checklist — what to check after each production release
- Terraform — who applies infrastructure changes