forge-et-iaac — a developer’s change is a PR to dev
The detail behind git-conventions.md § forge-et-iaac. Read this file before branching, pushing
or opening a PR in forge-et-iaac.
forge-et-iaac (the DevOps repository, AD #23) is not one of the four delivery repos and has its
own conventions:
- Its trunk is
dev, notmain. A developer (Tharinda, Dinil, and any other delivery-team member, and every Claude session working for one) branches fromdevand opens the PR against it (gh pr create --base dev), and never pushes todevdirectly. The DevOps team, Shyamin Ayesh and Senuthmi Thimansa, may push todevdirectly (the lead’s rule, 2026-10-05), so a change ondevwith no PR is expected and not a finding. - When
devchanges, the harness documents that describe the estate are updated —.forge/design/environments-and-identity.md§4 (what is applied, the open PRs), the register’s “Start here” steps and A-5 (.forge/cloud-gated-validation.md), and the open-risks paragraph of.forge/active-context.md. Readgit -C ../forge-et-iaac log origin/devat the start of any F38 work and after the DevOps team reports a change; the standing reminder is in.forge/owed.md. The deploys live in the app repos —forge-et-be(.github/workflows/build.yamland.aws/td.dev.json),forge-et-feandforge-et-pwa(.github/workflows/build.yamlin each; the capture app’s came from the delivery team’s forge-et-pwa#91) — and the DevOps team may push changes to them straight tomain(git-conventions.md§ Branch Protection), so readgit -C ../<app-repo> log origin/main -- .aws .github/workflowsfor each at the same time. - Terraform is written in a linked worktree, never in the checkout.
protected-paths.shallows the Edit and Write tools on.tfand.tfvarsfiles only under$WS/worktrees/<ticket>/…/forge-et-iaac/— a worktree made, fromorigin/dev, for a work item whose plan was approved — and still refuses them in$WS/forge-et-iaacitself and in every other repository. Never write Terraform through Bash to get past the hook. - Every Secrets Manager secret is declared in one shared base module, never in a module of its
own per feature (Shyamin Ayesh’s request, 2026-10-25):
base/secrets, where a new secret is a new key in its list (forge-et-iaac#9). Each secret is still created without a value (noaws_secretsmanager_secret_version), its value set by hand. A change that would move a secret’s address uses amovedblock, so the plan shows a move, not a destroy: a destroyed secret loses its value and keeps its name reserved for the recovery window. - Check before review, and get the plan from the workflow. Before asking for review, run
terraform fmt -check -recursiveat the root, thenterraform init -backend=falseandterraform validateinoverlays/devand inoverlays/uat(dev.yamlchecks onlyoverlays/dev, so abase/change that breaks the other overlay passes CI), each on its own line with its exit status, with Terraform 1.12.1 (the versiondev.yamlpins) or, when it is not installed, thehashicorp/terraform:1.12.1Docker image (docker run --rm -v "$PWD":/w -w /w hashicorp/terraform:1.12.1 <command>). Never runterraform planorapplylocally: the delivery team cannot read theet-opsstate. A plan of a branch comes fromgh workflow run dev.yaml --repo altrium-io/forge-et-iaac --ref <branch>: a manual run uses the branch’s owndev.yaml, which plans and applies only when the branch isdev. It runs withsvc-github’s administrator key, so ask the lead before starting it. - Every PR to
devgets a review before it merges, the DevOps team’s included (the lead’s rule, 2026-11-08):/forge-review-pr forge-et-iaac#<N>, which runs the checks, dispatches theiaac-revieweragent and posts its verdict on the PR. That posted verdict is the record: the repository has no required checks, so the record is a comment whose first line is<!-- forge-review v=1 sha=<head> verdict=<approve|block> -->. A push after it gets a delta review. Whoever in the delivery team first sees an unreviewed PR runs it; the PR’s author never waits for a particular person.- A finding is fixed on the PR, or given a home before the merge —
.forge/owed.mdwith an owner,.forge/bugs.md, or the register — so a PR merged without the fix leaves a row the team walks. A DevOps-team PR’s fixes are the author’s to make; the reviewer posts and does not push unless the author agrees on the PR. - A merged PR that was never reviewed gets the post-mortem review
/forge-review-prstep 1 describes: posted on the PR, each finding marked fixed since, still open or no longer applying againstorigin/dev, and each still-open one given a home. - A DevOps-team push straight to
devis reviewed the same way after the fact, by whoever next readsgit -C ../forge-et-iaac log origin/dev(at the start of any F38 work, as the bullet on the harness documents says): the commits since the last reviewed one, with the findings posted as a comment on the most recent open PR todevor, when none is open, recorded only in their homes.
- A finding is fixed on the PR, or given a home before the merge —
- A PR merges only after Shyamin Ayesh has approved it; after his approval anyone with write
access may merge it, with a merge commit (the lead’s rule, 2026-10-21). A commit pushed after
his approval is named on the PR, as forge-et-iaac#3 did for
a359b61. The review above comes first, so his approval is given with the verdict in front of him. - Request review from everyone else with write access there: Shyamin Ayesh (
shyaminayesh), Senuthmi Thimansa (senuthmi07), Tharinda (tharinda-altrium), Dinil (dinil-gamage) and Nanndish (nanndish-altrium) — the four who did not open the PR, passed with--reviewer(the organisation’s administrators, who also appear in the collaborators list, are not requested). The repository has no CODEOWNERS file, so nothing requests them automatically. Biseni does not have write access yet (read only, as of 2026-11-19 — re-check withgh api --paginate repos/altrium-io/forge-et-iaac/collaborators --jq '.[]|.login+" "+.role_name'; without--paginatethe first page leaves some people out); when someone is given write access, they join the reviewer list. - This is a team rule, not an enforced one: as of 2026-11-19
devhas no branch protection and no ruleset of its own — only the organisation’s repository-level rules (gh api repos/altrium-io/forge-et-iaac/rules/branches/dev) — so GitHub would accept a direct push. - The temporary
uatinstance is applied only by hand.uat.yaml(forge-et-iaac#11) plans, applies or destroysoverlays/uatwhen someone starts it ondev; no push or PR runs it. One instance is kept, with its data, from Phase 1’s round through Phase 2’s, then destroyed when the lead decides (AD #23, revised 2026-11-18); a fresh instance comes up in three steps (F38-h spec Rev 7). Any run is a billed AWS write, so a delivery-team session asks the lead first (.claude/CLAUDE.md§ ASK FIRST). Because the instance stays up, an apply fromdevbrings in everybase/change merged since the last one, so check that the running UAT backend handles each new scheduled job before applying (.forge/owed.md, theprice-broadcast-sendrow). - Only
devapplies on a push.dev.yamlruns on a push todev(a merged PR or a DevOps push), which plans and then applies withterraform apply -auto-approve, and on a manual run, which plans on the chosen branch and applies only when that branch isdev. A branch pushed for review runs nothing, so its commits need no[skip ci]. So a merge todevchanges the dev estate within minutes: read the merge’sdev.yamlrun (gh run list --repo altrium-io/forge-et-iaac --branch dev) and itsterraform::applystep. GitHub runs the workflow file from the pushed commit, so this holds only while each branch’sdev.yamlkeeps these rules; a branch cut fromdevbefore forge-et-iaac#3 merged (d230b133, 2026-10-20) carries the older file, which runs on every push to any branch with its apply step commented out, so mergedevinto it before pushing. - A change that a backend handler consumes waits as a draft PR until the handler runs on dev
(
.forge/lessons.mdL-319). A schedule, a queue’s consumer wiring or a route that the backend must handle goes in its own wave with no gate anddepends_on: [], run in a second session with/forge-deliver <TICKET> --wave <N>beside the code wave, and its PR is opened as a draft whose body says why. Mark it ready only after the backend wave PR that adds the handler has merged and dev’s running task definition uses an image built from a commit that contains that merge (aws ecs describe-services, thenaws ecs describe-task-definitionfor the image tag, thengit merge-base --is-ancestor <merge> <image commit>). The WI’s plan carries a subtask that checks this at each--wave <N>resume and marks the PR ready only when it holds (F37-a-WI-2.1 subtask 8), because Stage 14 does not.base/is shared, so the next UAT or production apply from adevthat holds the change creates it there too: in the wave’s harness half, add anowed.mdrow for the owners of those applies to check that the backend released there already includes the handler. Why: a merge todevapplies at once, and a schedule that fires before its handler exists is refused every minute and dead-lettered; a per-wave gate holds back only the dispatch, not the merge (F20-g, F37-a).