fix(examples): release-branch cuts its tag in a job, so a gate has somewhere to attach #24

Merged

mikluko merged 1 commit from mikluko/octant/1720-publish-gate into main

2026-09-06 20:59:24 +00:00

mikluko commented

2026-09-06 20:56:27 +00:00

(Migrated from github.com)

Octant: Q1720, on map D1727. Examples and prose only — the action does not change.

Every push to a release branch publishes, and a push arrives without a pull request. A merge to the trunk is gated because it comes through one; a push to release/* is gated by nothing.

The example did not have the bug and taught the shape that produces it. It carries no test job, so nothing was missing — but the tag was cut in a step inside the changelog job, so there was no job boundary a needs: could attach to. A reader adding a test job the obvious way could not gate the publish without restructuring first.

What changed

The cut becomes a job in both release-branch.yaml and main.yaml:

  tag:
    needs: [changelog]        # add your test job here
    if: >-
      needs.changelog.outputs.prerelease == 'true' &&
      needs.changelog.outputs.already-tagged == 'false'

needs: is job-level, so the cut has to be a job for a gate to have anywhere to attach. That is the whole reason for the split.

No test job is added. These examples demonstrate the action, not a whole pipeline, and a placeholder running nothing is a lie in a file people copy. The needs: list and one README section name where a real one goes.

A side effect worth having: both files now keep contents: read at the top and grant contents: write on the tag job alone, so nothing but the cut can push.

What was rejected, and why

The adopting repository proposed restructuring from one file per trigger to one file per branch class. It deletes the two-reasons paragraph in pull-request.yaml outright rather than arguing it better, which is a real win. Against it: three workflow files become five, while D1727's destination asks for the example "at roughly a third of its present size"; and the tag job must then carry if: github.event_name == 'push' or opening a pull request into the stabilization branch cuts and publishes a candidate — a sharper edge than anything in the current arrangement.

release-trunk is untouched: its example cuts no tag at all, so it has no gate to add.

Suite green, vet and gofmt clean, workflows parse, document reads valid=true.

Octant: [Q1720](http://127.0.0.1:9876/Q1720), on map [D1727](http://127.0.0.1:9876/D1727). Examples and prose only — the action does not change. Every push to a release branch publishes, and a push arrives without a pull request. A merge to the trunk is gated because it comes through one; a push to `release/*` is gated by nothing. **The example did not have the bug and taught the shape that produces it.** It carries no test job, so nothing was missing — but the tag was cut in a *step* inside the `changelog` job, so there was no job boundary a `needs:` could attach to. A reader adding a test job the obvious way could not gate the publish without restructuring first. ## What changed The cut becomes a job in both `release-branch.yaml` and `main.yaml`: ```yaml tag: needs: [changelog] # add your test job here if: >- needs.changelog.outputs.prerelease == 'true' && needs.changelog.outputs.already-tagged == 'false' ``` `needs:` is job-level, so the cut has to be a job for a gate to have anywhere to attach. That is the whole reason for the split. **No test job is added.** These examples demonstrate the action, not a whole pipeline, and a placeholder running nothing is a lie in a file people copy. The `needs:` list and one README section name where a real one goes. **A side effect worth having:** both files now keep `contents: read` at the top and grant `contents: write` on the `tag` job alone, so nothing but the cut can push. ## What was rejected, and why The adopting repository proposed restructuring from one file per trigger to one file per branch class. It deletes the two-reasons paragraph in `pull-request.yaml` outright rather than arguing it better, which is a real win. Against it: three workflow files become five, while D1727's destination asks for the example "at roughly a third of its present size"; and the tag job must then carry `if: github.event_name == 'push'` or opening a pull request into the stabilization branch cuts and publishes a candidate — a sharper edge than anything in the current arrangement. `release-trunk` is untouched: its example cuts no tag at all, so it has no gate to add. Suite green, `vet` and `gofmt` clean, workflows parse, document reads `valid=true`.