Skip to content

chore(ci): document main branch protection at release boundary (#108) #123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
w7-mgfcode merged 1 commit into from
May 14, 2026
Merged

chore(ci): document main branch protection at release boundary (#108) #123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/GIT-GITHUB-GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@ flowchart LR
| Branch Type | Purpose | Protection | Lifecycle |
| --- | --- | --- | --- |
| `feat/*` | Feature work | No strict protection | Deleted after merge |
| `dev` | Integration | CI checks required | Long-lived |
| `main` | Release | Strict CI + release flow | Long-lived |
| `dev` | Integration | CI checks required (4 gates: Lint & Format, Type Check, Test, Migration Check) | Long-lived |
| `main` | Release | Same 4 CI gates + release flow | Long-lived |
| `phase-*` | Audit snapshot | Protected, immutable | Permanent |

---
Expand Down Expand Up @@ -118,7 +118,7 @@ sequenceDiagram
### 4.2 Release Flow

1. Create PR from `dev` → `main` when integration is stable.
2. CI must pass on the PR.
2. CI must pass on the PR — the four `main` gates (Lint & Format, Type Check, Test, Migration Check) are enforced at the branch-protection layer, so the merge button stays disabled until they go green.
3. Merge to `main` triggers release-please.
4. If a release is created, artifacts are built and attached to the GitHub Release.

Expand Down
6 changes: 3 additions & 3 deletions docs/_base/PIPELINE_CONTRACT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,15 +37,15 @@ A "release commit" only occurs when a maintainer merges the open Release PR —

## Merge Conditions (ALL must be true)

Branch protection (verified via `gh api repos/w7-mgfcode/ForecastLabAI/branches/{dev,main}/protection` on 2026-05-12):
Branch protection (verified via `gh api repos/w7-mgfcode/ForecastLabAI/branches/{dev,main}/protection` on 2026-05-14):

- [ ] **`dev`** — required status checks (strict, must be up-to-date): `Lint & Format`, `Type Check`, `Test`, `Migration Check`; `required_approving_review_count: 1`; `dismiss_stale_reviews: true`; `allow_force_pushes: false`; `allow_deletions: false`.
- [ ] **`main`** — `required_approving_review_count: 1`; `allow_force_pushes: false`; `allow_deletions: false`; no required status checks at the branch-protection layer (release-please-managed; `cd-release.yml` runs after merge).
- [ ] **`main`** — required status checks (strict, must be up-to-date): `Lint & Format`, `Type Check`, `Test`, `Migration Check`; `required_approving_review_count: 1`; `dismiss_stale_reviews: false`; `allow_force_pushes: false`; `allow_deletions: false`. Mirrors the four `dev` gates so the release boundary (`dev` → `main`) cannot land with broken CI (issue #108).
- [ ] Conventional Commit message validated by `.claude/hooks/check-commit-format.sh` locally.
- [ ] No unresolved review comments.
- [ ] Branch up-to-date with `dev` (for `dev` merges) or `main` (for `dev → main` PRs).

> Note: `enforce_admins: false` on both branches — admin merge is possible (see "release-please skipped the bump after a dev → main merge" runbook), but should be reserved for the empty-`feat:`-trigger workaround.
> Note: `enforce_admins: false` on both branches — admin merge is possible (see "release-please skipped the bump after a dev → main merge" runbook), but should be reserved for the empty-`feat:`-trigger workaround. **With the `main` status-checks added (#108), an admin-merge of the empty-`feat:` trigger still has to wait for the same four CI jobs to complete on the trigger PR before merging — plan for ~3-5 min wall-clock between push and merge.**

## Failure Gates

Expand Down
2 changes: 1 addition & 1 deletion docs/_base/RUNBOOKS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ gh run view <cd-release-run-id> --log | grep -E "(Considering|No user facing)"
1. Open an issue tracking the release (`release: cut vX.Y.Z for ...`).
2. Branch off `dev`: `git switch -c feat/release-trigger-X-Y-Z`.
3. `git commit --allow-empty -m "feat(release): trigger vX.Y.Z release for <slice> (#<issue>)"`.
4. PR to `main`, CI green, admin-merge — the empty `feat:` becomes the merge subject and release-please bumps PATCH (pre-1.0 config). Reference example: PRs #99 → #100 → #101 for v0.2.8.
4. PR to `main`, **wait for all four `main` status checks to go green** (Lint & Format, Type Check, Test, Migration Check — enforced at the branch-protection layer since #108), then admin-merge — the empty `feat:` becomes the merge subject and release-please bumps PATCH (pre-1.0 config). Reference example: PRs #99 → #100 → #101 for v0.2.8. Plan ~3-5 min between push and the merge button becoming available.

## Break-Glass Procedures

Expand Down