You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(skills): fix CI/CD pipeline docs — source-verified from actual workflow files
All trigger tables, branch/tag maps, and pipeline diagrams were wrong
or incomplete. Fixed against the actual .github/workflows/ source:
- workflow-map.md: testing branch is the PRIMARY :testing publish path,
not just a source branch for PRs. Added correct branch→tag mapping
table verified from publish.yml setup job logic. Fixed build.yml
trigger to include push: main/next/testing (was missing entirely).
- ci.md skill: replaced broken Common Rationalizations table (had
workflow names as "rationalizations") with a correct Workflow Quick
Reference table. Added push column to Trigger Behavior table.
Fixed duplicate step numbers in Core Process.
- release-promotion.md: fixed Promotion Map (was showing main merge
as the start; testing push is the actual start). Fixed duplicate
step 2 in Core Process.
- quickstart.md: fixed duplicate rule 2 in Always Rules.
- docs/ci.md: fixed build job trigger row (said 'schedule' which does
not exist; was missing push trigger). Fixed publish pipeline diagram
to show main|testing|next, not just main.
Assisted-by: Claude Sonnet 4.6 via GitHub Copilot
|`e2e`|`pull_request` when `elements/`, `files/`, `patches/`, `Justfile`, or `project.conf` changed | Smoke test in QEMU via projectbluefin/testsuite |
9
-
|`build`|`merge_group`, `schedule`, `workflow_dispatch`(skips on `pull_request`)| Full OCI build (~60–90 min) |
9
+
|`build`|`push: main/next/testing` (paths-ignore: `.github/workflows/**`, `docs/**`, `**.md`, `AGENTS.md`), `merge_group`, `workflow_dispatch`— skips on `pull_request`| Full OCI build (~60–90 min) |
Copy file name to clipboardExpand all lines: docs/skills/ci.md
+58-18Lines changed: 58 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,12 +30,45 @@ Use this skill when the task mentions:
30
30
- OCI image contents or layer assembly → `oci-layers.md`
31
31
- Normal PR review → `pr-review.md`
32
32
33
+
## ⚠️ Builder Discipline — Read Before Doing Anything
34
+
35
+
**ONE BST build at a time. Always.**
36
+
37
+
Before merging, pushing, or dispatching any workflow, run the mandatory pre-flight:
38
+
39
+
```bash
40
+
gh run list --repo projectbluefin/dakota --limit 30 \
41
+
--json databaseId,status,name,headBranch \
42
+
| python3 -c "
43
+
import json, sys
44
+
runs = json.load(sys.stdin)
45
+
active = [r for r in runs if r['status'] in ('in_progress', 'queued', 'pending', 'waiting')]
46
+
if active:
47
+
print(f'BLOCKED: {len(active)} active run(s). Cancel all before proceeding:')
48
+
for r in active:
49
+
print(f' gh run cancel {r[\"databaseId\"]} --repo projectbluefin/dakota # {r[\"name\"]} [{r[\"headBranch\"]}]')
50
+
else:
51
+
print('OK: field is clear')
52
+
"
53
+
```
54
+
55
+
If output is not `OK: field is clear` — **cancel every listed run first**.
56
+
57
+
**Cache-warm is not exempt.** It shares the same `ubuntu-24.04` runner pool and CAS write bandwidth as real builds. Two concurrent BST jobs do not halve wall time — they more than double it and risk 6-hour timeouts with zero elements cached.
58
+
59
+
The rationalizations that have caused real production failures:
60
+
- "Cache-warm is additive, it helps the build" → **No. Cancel it.**
61
+
- "This is almost done, just a few minutes" → **Cancel it. You don't know that.**
62
+
- "It's a different branch, it won't interfere" → **Same runners and CAS. Cancel it.**
63
+
- "I cancelled one, that's enough" → **Cancel ALL. Re-run pre-flight.**
64
+
33
65
## Core Process
34
66
35
-
1.**Classify the failure before reading logs.**
67
+
1.**Run the mandatory pre-flight above. Verify `OK: field is clear`.**
- Need boot-check / smoke / testsuite behavior → `e2e-ci.md`
@@ -57,26 +90,33 @@ Use this skill when the task mentions:
57
90
| conflicting chore PRs, stale queue branches |`merge-queue.md`|
58
91
| historical edge cases and deep cuts |`ci-reference.md`|
59
92
60
-
## Common Rationalizations
93
+
## Workflow Quick Reference
61
94
62
-
|Rationalization|Reality|
63
-
|---|---|
64
-
|`.github/workflows/build.yml`| BST build + push artifacts to remote CAS. Fires on `merge_group` and `workflow_dispatch` only (no schedule). Does NOT push to GHCR directly. |
65
-
|`.github/workflows/publish.yml`|3-stage pipeline: setup → publish → promote. Pulls artifact from CAS, exports OCI, pushes `:$sha`, signs, attests, then immediately promotes to `:testing` on every successful merge. No e2e gate — that lives only in the weekly promotion. |
66
-
|`.github/workflows/promote-testing-to-main.yml`|Thin caller for `reusable-promote.yml` in `projectbluefin/actions`. Fires on `push: testing`, nightly schedule (23:00 UTC), and `workflow_dispatch`. Opens or updates the promotion PR that gates `:testing` → `:stable`. |
67
-
|`.github/workflows/execute-release.yml`|Fires on `push: main` + `workflow_dispatch`. A `check-trigger` job reads the squash-merge commit message — only proceeds when it starts with `ci: promote testing images to stable`. Calls `reusable-execute-release.yml` (copies image tags) then `reusable-release.yml` (generates GitHub Release + SBOM diff). |
68
-
|`.github/workflows/e2e.yml`|Smoke test via projectbluefin/testsuite. Fires on PR; `should-run` job skips the test when no image-affecting paths changed. |
69
-
|`.github/workflows/vulnerability-scan.yml`|Weekly Monday 08:00 UTC CVE scan via `reusable-vulnerability-scan.yml`. Also available as `workflow_dispatch` with optional `image_ref` input. Results surface in the GitHub Security tab.|
95
+
|Workflow|Trigger | What it does|
96
+
|---|---|---|
97
+
|`build.yml`|`push: main/next/testing` (paths-ignore: docs/workflows/md), `merge_group`, `workflow_dispatch` — NOT `pull_request`| BST build → artifacts into remote CAS. Does NOT push to GHCR. `validate` job runs on `pull_request` only; `build` job runs on everything else. |
98
+
|`publish.yml`|`workflow_run` from `build.yml` (branches: main, next, testing, + their gh-readonly-queue/* paths) | Export from CAS → push `:$sha` → sign/attest → promote to `:testing`/`:next`. No build happens here. |
99
+
|`promote-testing-to-main.yml`|`push: testing`, `schedule: Tue 04:00 UTC`, `workflow_dispatch`| Opens/updates promotion PR from testing into main. |
100
+
|`pr-release-gate.yml`|`pull_request` to `main`| Gates the promotion PR via cosign verify of `:testing`. |
101
+
|`execute-release.yml`|`push: main`, `workflow_dispatch`| Reads commit message — proceeds only when it starts with `ci: promote testing images to stable`. Copies tags to `:latest`/`:stable`, creates GitHub Release. |
102
+
|`cache-warm.yml`|`schedule: Mon/Thu 06:00 UTC`, `workflow_dispatch`| Pre-warms remote CAS. Two parallel jobs (x86_64, aarch64), `continue-on-error: true`. **Not exempt from pre-flight — cancel before any real build.**|
|`e2e`| Yes (change-detected) | No | No | Yes | No |
110
+
|`build`| No | Yes (paths-ignore) | Yes | Yes | No |
111
+
|`cache-warm`| No | No | No | Yes | Mon/Thu 06:00 UTC |
112
+
| Push to GHCR? | No | Via publish.yml | Via publish.yml | Via publish.yml | No |
113
+
114
+
**push paths-ignore:**`.github/workflows/**`, `docs/**`, `**.md`, `AGENTS.md` — doc/workflow-only pushes do NOT trigger a build. This is intentional; it means a CI-only commit advancing the branch HEAD will leave no build artifact for that SHA.
115
+
116
+
**Branch → tag mapping** (verified from publish.yml source):
117
+
-`main` or `gh-readonly-queue/main/*` → `:testing`
118
+
-`testing` or `gh-readonly-queue/testing/*` → `:testing`
119
+
-`next` or `gh-readonly-queue/next/*` → `:next`
80
120
81
121
**PR path:**`validate` + `e2e` (change-detected) — zero remote execution. ~15 min cached, ~30 min cold.
|`main`| merged changes build, publish `:$sha`, then promote to `:testing`|
89
-
|`testing`| source branch for promotion PRs into `main`|
90
-
|`next`| rolling GNOME master stream; publish to `:next` and `:btw`, never stable. No PR requirement on branch protection (dev stream, direct push from `sync-next-from-main` is intentional) |
91
-
|`gh-readonly-queue/main/*`| merge-queue build path for `main`|
92
-
|`gh-readonly-queue/next/*`| merge-queue build path for `next`|
|`main`| merge of promotion PR |`:latest`, `:stable`| Only via `execute-release.yml` and only when commit message starts with `ci: promote testing images to stable`. Normal merges do NOT produce a new tag. |
90
+
|`next`|`push` or `sync-next-from-main` dispatch |`:next`, `:btw`| Rolling GNOME master; never stable. No PR requirement on branch protection. |
91
+
|`gh-readonly-queue/main/*`| merge-queue | (build only, no tag) | Gate before merge to `main`. |
92
+
|`gh-readonly-queue/next/*`| merge-queue | (build only, no tag) | Gate before merge to `next`. |
0 commit comments