diff --git a/docs/skills/ci/SKILL.md b/docs/skills/ci/SKILL.md index e596fbb2..3d31ae5c 100644 --- a/docs/skills/ci/SKILL.md +++ b/docs/skills/ci/SKILL.md @@ -50,6 +50,18 @@ gh run rerun RUN_ID --repo projectbluefin/bluefin --failed-only Read the actual workflow before describing or changing its behavior. Shared logic belongs in the reusable workflow that owns it; callers should stay thin. +A pull request whose head branch lives on a fork reports **zero** checks until a +maintainer approves the run. That looks identical to "checks still queued", so +confirm the state before waiting on it: + +```bash +gh pr view PR --repo projectbluefin/bluefin --json headRepositoryOwner,maintainerCanModify +gh api -X POST repos/projectbluefin/bluefin/actions/runs/RUN_ID/approve +``` + +`maintainerCanModify: true` also means fix commits can be pushed straight to the +contributor's branch. + Containerfile stages that consume source through bind mounts inherit the mounted stage's image ID as part of their cache key. Give the package stage its own narrow `scratch` context so unrelated edits do not invalidate it, and pass an @@ -63,6 +75,25 @@ MergeRaptor installation token to update one `testing-lab / bluefin` Check Run for the exact PR head SHA. Do not duplicate the result in a PR comment or commit status. +## Workflow input and job constraints + +A `type: string` input is truthy in an `if:` even when its value is `"false"`. +Gating on the bare input therefore fails **open**. Compare explicitly and treat +any unexpected value as the safe state: + +```yaml +if: inputs.publish_stream_tag == 'true' +``` + +A job that calls a reusable workflow accepts only `name`, `uses`, `with`, +`secrets`, `needs`, `if`, and `permissions`. `continue-on-error` and +`runs-on` are rejected, so a reusable-workflow call cannot be made advisory — +it either gates or it is absent. `actionlint` catches this. + +A job listed in `needs:` without `always()` makes its dependents `skipped` when +it fails. Confirm whether a promotion job is *failing* or *never running*; the +two look the same in the UI and have different fixes. + ## Hard rules - Verify the pull request base branch before debugging missing checks. @@ -113,3 +144,6 @@ Read the affected YAML, identify the owning reusable workflow, validate locally. - Changing a caller when the behavior belongs in shared workflow logic. - Posting a lab result as a PR comment instead of updating the MergeRaptor Check Run. +- Reading a gate's log message as proof of what it did. A step can report that a + tag was excluded and push it anyway; confirm against the pushed artifact. +- Treating a fork PR with no checks as pending rather than unapproved. diff --git a/docs/skills/release-artifacts/SKILL.md b/docs/skills/release-artifacts/SKILL.md index a04b1801..deba48bd 100644 --- a/docs/skills/release-artifacts/SKILL.md +++ b/docs/skills/release-artifacts/SKILL.md @@ -39,6 +39,26 @@ gh run view RUN_ID --repo projectbluefin/bluefin --log-failed gh run watch RUN_ID --repo projectbluefin/bluefin --exit-status ``` +## Verify a stream tag against its gate + +A stream tag (`:testing`, `:stable`) is a claim that a digest passed its gate. +Verify the claim rather than trusting the tag: resolve what the tag points at, +then confirm that digest actually passed. + +```bash +skopeo inspect docker://ghcr.io/projectbluefin/bluefin:testing --format '{{.Digest}}' +gh run list --repo projectbluefin/bluefin --workflow post-testing-e2e.yml --limit 20 +``` + +A promotion job reported as `skipped` while the stream tag still advanced means +something outside the gate is publishing it. Build-time tag computation is the +usual source: the bare stream tag can sit in the tag list that the push step +consumes, so excluding it from a conditional does not remove it from the push. +Filter the stream tag out of the list itself. + +Never re-point or delete a published stream tag to "repair" this — that is +user-visible and belongs to a human. + ## Red flags - Re-pulling a large image during release only to generate metadata. @@ -65,8 +85,11 @@ Read the workflow, verify the exact digest and artifact, then inspect the run. ## Red Flags - Guessing tags or bypassing a failed release gate. +- Trusting a stream tag as evidence of promotion without resolving its digest. +- A promotion job that has never succeeded, yet its stream tag keeps advancing. ## Verification - [ ] The selected source and focused command were checked. +- [ ] The stream tag's digest was resolved and traced to a passing gate run. - [ ] The repository default gate passes. diff --git a/docs/skills/worktrees/SKILL.md b/docs/skills/worktrees/SKILL.md index 454970bc..237f54eb 100644 --- a/docs/skills/worktrees/SKILL.md +++ b/docs/skills/worktrees/SKILL.md @@ -105,6 +105,23 @@ whether a branch is finished. `worktree.sh` asks the forge via `gh` instead. | `worktree already exists` | Stale directory from earlier work | `worktree.sh done `, or `git worktree prune` if the directory is already gone | | Untracked `.worktrees/` in `git status` | Hook and ignore rules predate this setup | Confirm `.worktrees/` is in `.gitignore` | | Uncommitted work blocks `done` | Real changes in the worktree | Commit them, or `git worktree remove --force` to discard | +| A repo script reports zero files | It filters `.worktrees` out by path and is running inside one | Run it from the main checkout, or fix the filter to be checkout-relative | + +Tooling that excludes `.worktrees/` by absolute path components silently matches +*everything* when it runs from inside a worktree. A validator that passes with a +zero-file count is failing, not succeeding — check the count, not the exit code. Never use `git add -A` or `git add .`. Stage explicit paths, then verify with `git status` and `git diff --cached --name-only` before committing. + +## Red Flags + +- Feature work committed directly in the main checkout. +- A validator or linter reporting suspiciously few files while run in a worktree. +- Removing a worktree with uncommitted changes instead of resolving them. + +## Verification + +- [ ] `bash .github/scripts/worktree.sh list` shows the expected worktrees. +- [ ] Repository checks were run and reported a non-zero file count. +- [ ] The main checkout is clean and on `testing` or `main`.