@avi2dg/checks 0.52.1 → 0.53.0

package/docs/design.md

@@ -186,24 +186,34 @@ So a checkout without tags, a fork, and a branch that merged `main` in all write
 A section keeps the date it was written, because the squash merge that lands the release commit may fall on another day.
 Entries come from commit subjects, which are the squash-merged pull request titles that commitlint holds to the conventional format.
 A commit body holds the branch's own messages, and nothing lints it, so no entry comes from a body.
-The changelog arrives in the release pull request, and no workflow pushes to a branch a person works on.
+The changelog arrives in the release commit, and no workflow pushes to a branch a person works on.
 
-## A release is cut every day
+## A release is cut from every push
 
 A release waits for no quiet moment, since a busy repository always has work under way.
-The daily release opens the release pull request from `main` whenever it holds a feature or a fix since the last tag, and the pull request merges through the repository's usual merge path once its checks pass.
+A package published to npm releases from every push to `main` that holds a feature or a fix since the last tag.
+A version only reaches its users once it is published.
+A daily release pull request would leave each merged change unpublished until a person merged the release too.
+`checks-release-push` builds the release commit on top of `main` and runs the required checks on it from the `release/<branch>` branch it owns.
+Only then does it move `main` to it without a force, so `main` only ever gains a release commit whose checks passed.
+It tags the commit it landed and nothing else.
+A repository that is no package keeps the daily release pull request.
 `checks-release-pr` writes only to the `release/<branch>` branch it owns, and rebuilds that branch on `main` rather than merging `main` into it, so the changelog it carries is the one the build writes.
 `checks-release-tag` writes only the `v*` tag of a release commit that already landed.
 The `github-release` job's `contents: write` creates or updates the GitHub release from the tag's `CHANGELOG.md` section.
 
-Both jobs act with the workflow token.
+Every release bin acts with the workflow token.
 GitHub starts no run for a push that token makes, and holds the runs of a pull request it opens until a maintainer approves them.
 A GitHub App or a personal token would start them, but either is a credential each repository stores and someone rotates.
-So `checks-release-pr` dispatches the required checks on the release head, and `checks-release-tag` dispatches the release workflow on the tag, since a dispatch is the one run the token can start.
+A dispatch is the one run the token can start.
+So `checks-release-pr` and `checks-release-push` dispatch the required checks on the release head.
+`checks-release-tag` and `checks-release-push` dispatch the release workflow on the tag.
 GitHub keeps a dispatched run's checks off the pull request, and branch protection does not count them.
 So each dispatched job reports its result as a commit status named for the job, which a required check of that name counts.
 Where a status and a check share a name, branch protection requires both, so the status never passes a pull request whose own check failed.
-The cost is a `workflow_dispatch` trigger and a status step on each workflow a release needs, a title lint that reads its title from the open pull request, and the repository setting that lets the token open a pull request.
+The cost is a `workflow_dispatch` trigger and a status step on each workflow a release needs.
+The title lint reads its title from the open pull request, or lints the head subject when none is open.
+The daily release also needs the repository setting that lets the token open a pull request.
 
 ## The docs gate judges what a change touches
 
@@ -300,6 +310,18 @@ No finding can be accepted.
 A secret has no false positive worth keeping in git, because a placeholder carries the same shape without the value.
 So the gate ignores a repository's `.gitleaks.toml`, `.gitleaksignore` and `gitleaks:allow` comments, which would each let one repository pass what another fails.
 
+A person's name, an employer's domain, host names and IP ranges are no secret to gitleaks, yet a public repository must not carry them.
+A rule that names them would publish them, so the owner keeps the terms in a private pack outside every repository.
+The pack is a file rather than an inline variable, so one file serves the shell and the runner, and no workflow names a term.
+A pack that is set but cannot serve fails the gate, because a scan that quietly dropped it would pass what it exists to catch.
+An empty `CHECKS_SECRETS_PACK` counts as set, since a CI secret that is missing expands to an empty value.
+No report prints a matched term text or the pack path, because the report lands in a public CI log.
+A finding location prints as it stands, such as a file name or a link.
+So a term inside a file name or a repository name shows there.
+That location is already public in the scanned commit or the scanned pull request.
+
+A pull request's title, body and comments reach the forge without a commit, so [checks-pr-text](gates/checks-pr-text.md) scans them with the same rules and the same pack.
+
 ## The frontend checks are opt-in
 
 A browser check needs a built site and a browser, and a backend repository has neither.

package/docs/gates/checks-ci-wiring.md

@@ -23,7 +23,7 @@ It refuses a step or job with `if: false` or `continue-on-error: true`.
 It also refuses a workflow that does not trigger on both `opened` and `synchronize` pull requests to the target branch.
 A path filter cannot cover every pull request and therefore cannot satisfy the check.
 It refuses a reference to a workflow or job the repository does not hold.
-Each literal `checks-release-pr` and `checks-release-tag` argument names a workflow file, so every one must match a file under `.github/workflows/`.
+Each literal `checks-release-pr`, `checks-release-push` and `checks-release-tag` argument names a workflow file, so every one must match a file under `.github/workflows/`.
 A call counts directly, through `bunx`, or through `bun` or `bun run` with the bin's path or its source file.
 An argument built from a variable or an expression is known only when the job runs, so the check passes over it.
 An argument built by command substitution is known only when the job runs, so the check passes over it.

package/docs/gates/checks-commit-identity.md

@@ -15,7 +15,7 @@ A commit that GitHub committed allows any author name with an allowed email.
 GitHub authors a web merge under the account's display name.
 The same author on a commit with any other committer must match the allowed name too.
 `github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>` is allowed as author only of a commit whose subject is `chore: release <version>`, with or without the pull request number a squash merge adds.
-GitHub attributes the release commit [checks-release-pr](checks-release-pr.md) makes to that bot, since it commits through the workflow token.
+GitHub attributes the release commit [checks-release-pr](checks-release-pr.md) or [checks-release-push](checks-release-push.md) makes to that bot, since each commits through the workflow token.
 Such a commit may carry a `Co-authored-by` trailer naming that bot, since GitHub adds one to some squash merges of a pull request the bot opened, and every other trailer is refused.
 
 ## What it reads

package/docs/gates/checks-commit-title.md

@@ -8,12 +8,13 @@ audience: consumers
 
 ## What it checks
 
-It lints the pull request title and nothing else.
+It lints the pull request title, or the head subject when no open pull request heads the branch.
 The title comes from `PR_TITLE` when the event carries one.
 A dispatched run carries no pull request, so the bin reads the title of the one open pull request its branch heads.
-It fails when there is none.
+When none heads the branch, it lints the head subject as it stands and without ` (#0000)`.
+It fails when more than one heads the branch.
 A run with no title to lint passes and says so.
-The bin lints the title with ` (#0000)` attached, since GitHub appends the pull request number to the squashed subject.
+The bin lints a pull request title with ` (#0000)` attached, since GitHub appends the pull request number to the squashed subject.
 It moves the git comment character off `#`, so a title starting with `#` is linted like any other.
 
 ## What it reads
@@ -31,7 +32,7 @@ The bin takes no arguments.
 | Code | Result |
 | --- | --- |
 | 0 | The title lints clean, or there is no title to lint. |
-| 1 | The title breaks the rules, or no one open pull request heads the branch. |
+| 1 | The title or the head subject breaks the rules, or more than one open pull request heads the branch. |
 | 2 | The kit config or binary cannot be resolved, or a dispatched run misses its environment. |
 
 ## Sample output

package/docs/gates/checks-copy.md

@@ -13,9 +13,9 @@ It holds them to the three separator rules of [The prose rules](checks-docs.md#t
 
 | Refused | For example | Passes |
 | --- | --- | --- |
-| an em dash | `hexn.io — платформа` | `hexn.io, платформа` |
+| an em dash | `example.com — платформа` | `example.com, платформа` |
 | an en dash | `pages 1–5` | `pages 1 to 5` |
-| a hyphen used as a dash | `hexn.io - платформа` or `a -- b` | `well-known`, `kebab-case`, `1-5` and `--flag` |
+| a hyphen used as a dash | `example.com - платформа` or `a -- b` | `well-known`, `kebab-case`, `1-5` and `--flag` |
 
 A hyphen used as a dash is a run of one to three hyphens with white space on both sides and text on both sides.
 So a hyphen inside a word or a number, a flag and a list marker all pass.

package/docs/gates/checks-night-run.md

@@ -117,7 +117,7 @@ jobs:
           path: reports/mutation/mutation.json
           retention-days: 1
   tests:
-    runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
       - uses: oven-sh/setup-bun@v2
@@ -135,7 +135,7 @@ jobs:
   report:
     needs: [mutation, tests]
     if: ${{ !cancelled() && needs.tests.result == 'success' }}
-    runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}
+    runs-on: ubuntu-latest
     permissions:
       contents: read
       actions: read
@@ -176,9 +176,9 @@ It passes `--mutation` only when the mutation job succeeded, and the failed muta
 The concurrency group queues a run started by hand behind the scheduled one, so two runs never file the same finding twice.
 A dispatch on a branch runs both jobs and lists its findings in the report job's log, and `if-no-files-found: ignore` lets that run upload no record.
 `issues: write` on the report job is the one permission beyond reading the repository and its runs.
-A public repository keeps `runs-on: ubuntu-latest` on the mutation job.
+A public repository keeps `runs-on: ubuntu-latest` on every job.
 A private repository sets `runs-on` on the mutation job to the labels declared under `checks.mutationRunner` in `package.json`, and [checks-ci-wiring](checks-ci-wiring.md#runners) refuses a mutation job that names `CI_RUNS_ON`.
-The report job reads `CI_RUNS_ON`, because it runs no mutant.
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on the tests and report jobs.
 A successful run uploads `night-run`, so the next night compares with it, and a failed run uploads nothing a later night reads.
 The artifact keeps 90 days, so a gap of nights still leaves a previous night to compare with.
 

package/docs/gates/checks-pr-text.md

@@ -0,0 +1,90 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-pr-text
+
+`checks-pr-text` scans the title, the body and every comment of a public pull request for a secret or a term of the private pack.
+
+## What it checks
+
+It scans the title, the body, each conversation comment, each review and each review comment, with the rules [checks-secrets](checks-secrets.md) runs on a commit.
+On a fork's pull request a review or a review comment starts no scan, because GitHub gives those runs no secret.
+That text is scanned only when another trigger runs next.
+It adds the private pack when `CHECKS_SECRETS_PACK` names one, as [The private pack](checks-secrets.md#the-private-pack) describes, and its last line says whether the pack ran.
+With `CHECKS_SECRETS_PACK` set but the pack unable to serve, it exits 2 and scans nothing.
+It reads the text as it stands now, so a text edited clean passes on the next run.
+A finding names the text, its line and its rule, and never the matched text.
+A finding location prints as it stands, such as a link.
+So a term inside a repository name shows there.
+That location is already public in the scanned pull request.
+
+Deleting a finding from the current text leaves it in GitHub's edit history of that text, which the text's edit menu deletes revision by revision.
+The timeline keeps a renamed title's old text, and only GitHub Support removes it.
+
+## What it reads
+
+It calls `gh api` with `GH_TOKEN` for the pull request and its three kinds of comment, in the repository of the checkout's remote.
+It reads the path of the private pack from `CHECKS_SECRETS_PACK`, and the kit's rules from `src/delivery/gitleaks.toml` in the installed package.
+It writes each text to a file in a temporary directory, and deletes the directory when the scan ends.
+
+## Arguments
+
+| Argument | Meaning |
+| --- | --- |
+| `<pull-request-number>` | the number of the pull request to scan |
+
+## Exit codes
+
+| Code | Result |
+| --- | --- |
+| 0 | No text carries a secret or a term of the pack. |
+| 1 | A text carries a secret or a term of the pack. |
+| 2 | The argument is not one pull request number, `gh api` fails, no verified scanner is at hand, gitleaks fails, or `CHECKS_SECRETS_PACK` is set and the pack cannot serve. |
+
+## Sample output
+
+```
+pr-text: pull request 42 carries 2 secret(s) or private term(s); delete each from the text it names, and delete the revision GitHub keeps in that text's edit history:
+  the body:3 private-domain: A domain the private pack lists
+  https://github.com/owner/repo/pull/42#issuecomment-1:1 private-name: A name form the private pack lists
+pr-text: the kit's rules and the private pack CHECKS_SECRETS_PACK names ran
+```
+
+## When it runs
+
+A public repository runs it from a workflow of its own on every change to a pull request's text:
+
+```yaml
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened]
+  issue_comment:
+    types: [created, edited, deleted]
+  pull_request_review:
+    types: [submitted, edited]
+  pull_request_review_comment:
+    types: [created, edited, deleted]
+```
+
+The job writes the pack from a secret, as [The private pack](checks-secrets.md#the-private-pack) shows, then runs `bunx checks-pr-text` with the pull request's number.
+It skips the scan when the secret is unset, as [When no pack is configured](#when-no-pack-is-configured) says.
+`pull_request_target` runs the base branch's workflow with the repository's secrets, even for a fork's pull request.
+The job reads the text through the API and checks out none of the pull request's code, so a fork runs nothing there.
+A comment's run reports on no pull request, so the job posts its result as a `pr-text` status on the head commit.
+The kit's own `.github/workflows/pr-text.yml` is a complete example.
+
+## When no pack is configured
+
+The kit's workflow skips the scan when `CHECKS_SECRETS_PACK` is unset or empty, instead of failing.
+It writes a notice and a job summary line that say so, and posts a `pr-text` status of success whose description reads `scan skipped: no private pack is configured (CHECKS_SECRETS_PACK is unset)`.
+A skip is a coverage gap, not a pass: no private term was checked on that pull request.
+Only the repository secret decides a skip, so no input from a pull request's author can cause one.
+To scan with the pack, set the repository secret `CHECKS_SECRETS_PACK` to the pack's JSON, as [The private pack](checks-secrets.md#the-private-pack) describes.
+The next eligible run then scans the text with it.
+On a fork's pull request a review or a review comment still starts no run, so that text waits for another trigger.
+
+## Related topics
+
+- [checks-secrets](checks-secrets.md)
+- [checks-commit-title](checks-commit-title.md)

package/docs/gates/checks-release-notes.md

@@ -47,7 +47,7 @@ Released 2026-09-27.
 
 Each consumer owns `.github/workflows/release.yml` and calls the kit bins from it.
 The version lives in `package.json`, and the tag names the same version with a leading `v`.
-The build writes the changelog, so the release pull request carries the notes before the tag exists.
+The build writes the changelog, so the release commit carries the notes before the tag exists.
 A repository that publishes a package to npm releases with this workflow:
 
 ```yaml
@@ -80,7 +80,7 @@ jobs:
         with:
           node-version: 24
           registry-url: https://registry.npmjs.org
-      - run: npm publish
+      - run: ./node_modules/.bin/checks-release-publish
   github-release:
     needs: publish
     runs-on: ubuntu-latest
@@ -140,8 +140,9 @@ jobs:
 ```
 
 A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}` on each job in either workflow, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires.
-A release is a pull request that holds only the version bump and the built changelog.
-[checks-release-pr](checks-release-pr.md) opens it on the daily release's schedule, or on every push to `main` in a package repository.
+A release is one commit that holds only the version bump and the built changelog.
+A package repository lands it on every push to `main` through [checks-release-push](checks-release-push.md), which tags it and dispatches this workflow on the tag.
+Another repository takes it as the pull request [checks-release-pr](checks-release-pr.md) opens on the daily release's schedule.
 When it lands, [checks-release-tag](checks-release-tag.md) tags the merge commit and dispatches this workflow on the tag.
 A tag the workflow token pushes starts no `push` run, so the workflow triggers on `workflow_dispatch` as well, and refuses a dispatch on a ref that is not a tag.
 A tag a person pushes starts the same workflow through its `push` trigger.
@@ -156,3 +157,4 @@ A repository with no versioned releases does not need it.
 
 - [checks-changelog](checks-changelog.md)
 - [checks-release-report](checks-release-report.md)
+- [checks-release-publish](checks-release-publish.md)

package/docs/gates/checks-release-pr.md

@@ -75,15 +75,13 @@ release-pr: https://github.com/acme/widget/pull/12 releases 0.4.0 from 3f2a9c81d
 ## When it runs
 
 The daily release workflow below runs it once a day on the default branch.
-A package repository runs it on every push to `main` other than a release commit.
+A package published to npm releases each push to `main` through [checks-release-push](checks-release-push.md) instead, with no pull request.
 Run the workflow by hand with `gh workflow run daily-release` to refresh the release pull request sooner.
 
 ## Running it in CI
 
-A repository takes the daily release as `.github/workflows/daily-release.yml`.
+A repository takes the daily release as the `daily-release` workflow below.
 A consuming repository pins daily-release between 03:00 and 04:00 UTC at a minute chosen so repositories do not start together.
-A package repository released on push drops the `schedule` trigger, so every push to `main` but a release commit opens or refreshes the release pull request.
-Its `pull-request` job's `if` reads `"github.event_name != 'push' || !startsWith(github.event.head_commit.message, 'chore: release ')"`.
 The `pull-request` job checks out its branch's tip when it starts, so a run that starts late never rebuilds the release on an older commit.
 The `pull-request` job runs on the schedule, and the `tag` job runs when a release commit lands on `main`, as [checks-release-tag](checks-release-tag.md) says:
 
@@ -186,5 +184,6 @@ gh api --method PUT repos/<owner>/<repo>/actions/permissions/workflow -F can_app
 
 - [checks-release-report](checks-release-report.md)
 - [checks-release-tag](checks-release-tag.md)
+- [checks-release-push](checks-release-push.md)
 - [checks-changelog](checks-changelog.md)
 - [checks-release-notes](checks-release-notes.md)

package/docs/gates/checks-release-publish.md

@@ -0,0 +1,63 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-publish
+
+`checks-release-publish` publishes the version `package.json` holds to npm, unless npm already holds it or a newer version.
+
+## What it checks
+
+It reads the `latest` dist-tag of the package from npm.
+It runs `npm publish` when npm holds no version of the package yet, or when the version is above `latest`.
+It publishes nothing and ends cleanly when `latest` is the version, so a rerun of a release that published passes.
+It publishes nothing and ends cleanly when `latest` is above the version.
+The release workflow refuses a tag off `main`, so the newer version already carries every change of the older one.
+When `npm publish` fails, it reads `latest` again.
+A newer version that published while it ran ends it cleanly as well, and any other failure fails it.
+
+Two uploads that overlap can still leave `latest` on the older version, since the order check runs before either upload completes.
+`checks-release-push` holds its concurrency group until the release workflow it dispatched finishes for that reason, so releases it cuts publish one at a time, while a release workflow dispatched or rerun by hand relies on this bin alone.
+That hold ends early in two cases.
+One is when the 45 minute wait times out.
+The other is when polling fails past the retry bound or the dispatch of the release workflow fails after GitHub accepted it.
+In those cases an unfinished publisher can overlap the next release, and if latest lands on the older version the fix is npm dist-tag add <package>@<newer version> latest.
+
+## What it reads
+
+It reads `name` and `version` from `package.json` in the working directory.
+It reads `latest` with `npm view <name> dist-tags --json`, and takes npm's `E404` answer for a package npm does not hold yet.
+`npm publish` takes its registry and credentials from the workflow, as trusted publishing sets them.
+
+## Arguments
+
+```sh
+checks-release-publish
+```
+
+It takes no arguments.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | the version published, npm already holds it, or npm holds a newer version |
+| 2 | the arguments do not parse, `package.json` or npm's answer does not parse, or npm refuses the publish for a reason other than a newer version |
+
+## Sample output
+
+A release that runs after a newer one published prints one line:
+
+```
+release-publish: npm already holds @acme/widget@0.4.1, which carries every change in 0.4.0, so 0.4.0 stays off npm
+```
+
+## When it runs
+
+The release workflow of a package published to npm runs it in place of `npm publish`, as [checks-release-notes](checks-release-notes.md#release-workflow) shows.
+A repository that never publishes to npm does not need it.
+
+## Related topics
+
+- [checks-release-notes](checks-release-notes.md)
+- [checks-release-push](checks-release-push.md)

package/docs/gates/checks-release-push.md

@@ -0,0 +1,153 @@
+---
+kind: reference
+audience: consumers
+---
+# checks-release-push
+
+`checks-release-push` lands the next version of a package on its branch once the checks pass.
+It then tags the release and dispatches the release workflow on the tag.
+
+## What it checks
+
+It lists the unreleased changes the way [checks-release-report](checks-release-report.md) does, and does nothing when there are none.
+It bumps the version `package.json` holds by the rule [checks-release-pr](checks-release-pr.md#what-it-checks) states, and refuses what that bin refuses.
+It refuses when `v<version>` of the next version already tags a commit, since a version is released once.
+It writes the next version into `package.json` and runs `bun run build`, which writes `CHANGELOG.md`.
+It commits both as `chore: release <version>` on top of `HEAD` through the GitHub API, as `checks-release-pr` does.
+It points the branch `release/<branch>` at that commit and dispatches every check workflow its arguments name there.
+It waits up to 45 minutes in all for those workflows to finish on the release commit.
+It reads the newest run of each, so a rerun stands in for the run it repeats.
+A failed read of the runs list does not end the wait.
+The wait retries the read at the same interval.
+A successful read resets the count of failed reads in a row.
+Past four failed reads in a row the run fails with the last read error.
+When any of them concludes short of success, it refuses and leaves `<branch>` and the tags alone.
+When all of them pass, it moves `<branch>` to the release commit without a force.
+GitHub refuses that update when `<branch>` moved while the checks ran.
+The run then ends cleanly, since the run of the push that moved it releases the new head.
+When the update fails but `<branch>` already holds the release commit, the update landed and the run goes on.
+It then tags the release commit `v<version>`, pushes the tag and dispatches the release workflow on it, and waits up to 45 minutes for that workflow's run on the release commit to finish.
+When that run concludes short of success, or does not finish in time, the bin fails, though `<branch>` already holds the release and the tag exists.
+When `HEAD` is itself a release commit, it tags it as [checks-release-tag](checks-release-tag.md) does, and waits for the release workflow it dispatches the same way.
+So a rerun after a failed tag push finishes the release.
+It leaves the working tree as it found it.
+
+No pull request is opened, so a package release needs neither a merge by hand nor the setting that lets the token open pull requests.
+
+## What it reads
+
+It reads the `v*` tags, the commit subjects since the last one and `package.json` from the checkout.
+It refuses a shallow checkout, a detached `HEAD` and a working tree with changes to tracked files.
+It reads the tags and the branch from `origin` with `git ls-remote`, and pushes the tag with the credentials the checkout holds.
+It calls the GitHub API through `gh api`, which takes the repository from the checkout's remote and the token from `GH_TOKEN`.
+The token needs `contents: write` and `actions: write`.
+The branch's protection must let the workflow token push a commit whose required checks passed, so it requires status checks and no pull request review.
+
+## Arguments
+
+```sh
+checks-release-push <release-workflow> <workflow>...
+```
+
+The first argument names the release workflow file under `.github/workflows/`, such as `release.yml`, which triggers on `workflow_dispatch` and keeps its own guards, as [checks-release-notes](checks-release-notes.md) shows.
+Each later argument names a workflow file whose jobs report the checks the branch requires, such as `ci.yml`.
+Each named workflow triggers on `workflow_dispatch`.
+Name no check workflow that runs something else on dispatch, such as a mutation baseline.
+
+## Exit codes
+
+| Code | When |
+| --- | --- |
+| 0 | nothing is unreleased, the branch moved while the checks ran, the release tag already tags `HEAD`, or the release landed and its release workflow finished |
+| 2 | the arguments do not parse, a refusal above applies, a check fails or does not finish in time, the build fails, the push or a GitHub API call fails, or the dispatched release workflow fails or does not finish in time |
+
+## Sample output
+
+A run that releases prints the build's own output, then three lines:
+
+```
+release-push: dispatched ci.yml on release/main to check 0.4.0 at 3f2a9c81d0b4
+release-push: released 0.4.0 as 3f2a9c81d0b4 on main, tagged it v0.4.0, and dispatched release.yml on it
+release-push: release.yml finished on v0.4.0
+```
+
+A run whose release workflow fails refuses with the run that failed, though the branch already holds the release and the tag exists:
+
+```
+checks-release-push: the release workflow failed on 3f2a9c81d0b4: release.yml concluded failure at https://github.com/acme/widget/actions/runs/7
+```
+
+A run whose checks fail refuses with the run that failed:
+
+```
+checks-release-push: the checks failed on 3f2a9c81d0b4, so the release stays off the branch: ci.yml concluded failure at https://github.com/acme/widget/actions/runs/7
+```
+
+## When it runs
+
+A package published to npm runs it on every push to `main`, so each merged feature or fix ships as a versioned release.
+Run the workflow by hand with `gh workflow run release-push` to cut a release now.
+
+## Running it in CI
+
+A package repository takes it as `.github/workflows/release-push.yml`:
+
+```yaml
+name: release-push
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  release:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    concurrency:
+      group: release-push
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      actions: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.ref }}
+          fetch-depth: 0
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+      - run: bun install --frozen-lockfile
+      - name: release what main holds once its checks pass
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ./node_modules/.bin/checks-release-push release.yml ci.yml
+```
+
+The push the workflow token makes starts no run, so landing the release commit never starts the workflow again.
+The concurrency group holds from reading the branch until the release workflow it dispatched finishes, so releases cut by release-push publish one at a time, and a queued run the group cancels had cut nothing.
+That hold ends early in two cases.
+One is when the 45 minute wait times out.
+The other is when polling fails past the retry bound or the dispatch of the release workflow fails after GitHub accepted it.
+In those cases an unfinished publisher can overlap the next release, and if latest lands on the older version the fix is npm dist-tag add <package>@<newer version> latest.
+[checks-release-publish](checks-release-publish.md) stays the guard for a release workflow dispatched or rerun by hand.
+A run that waits behind it checks out the branch's tip when it starts, so it releases on top of what landed.
+The job waits on the checks it dispatched and on the release workflow, so a hosted runner bills the minutes those workflows take.
+A private repository sets `runs-on: ${{ vars.CI_RUNS_ON || 'ubuntu-latest' }}`, as [checks-ci-wiring](checks-ci-wiring.md#runners) requires of every job but a mutation job.
+
+The other workflows accept the dispatch the way [checks-release-pr](checks-release-pr.md#running-it-in-ci) lists:
+
+- `.github/workflows/ci.yml` triggers on `workflow_dispatch` and grants `statuses: write` and `pull-requests: read`.
+- Each required job ends with the step that reports its result as a commit status.
+- The title lint lints the subject of the head commit when no open pull request heads the dispatched branch, as [Commit messages](../configs/commit-messages.md) says.
+- `.github/workflows/release.yml` triggers on `workflow_dispatch` and refuses a ref that is not a tag.
+
+## Related topics
+
+- [checks-release-report](checks-release-report.md)
+- [checks-release-pr](checks-release-pr.md)
+- [checks-release-tag](checks-release-tag.md)
+- [checks-release-notes](checks-release-notes.md)
+- [checks-release-publish](checks-release-publish.md)

package/docs/gates/checks-release-report.md

@@ -56,7 +56,7 @@ release-report: no unreleased changes since v0.1.0
 ## When it runs
 
 A person runs it to see what the next release holds.
-[checks-release-pr](checks-release-pr.md) reads the same changes before it opens the release pull request.
+[checks-release-pr](checks-release-pr.md) and [checks-release-push](checks-release-push.md) read the same changes before they cut a release.
 A repository with no versioned releases does not need it.
 
 ## Related topics
@@ -64,3 +64,4 @@ A repository with no versioned releases does not need it.
 - [checks-changelog](checks-changelog.md)
 - [checks-release-notes](checks-release-notes.md)
 - [checks-release-pr](checks-release-pr.md)
+- [checks-release-push](checks-release-push.md)

package/docs/gates/checks-release-tag.md

@@ -56,8 +56,10 @@ release-tag: tagged 3f2a9c81d0b4 as v0.4.0, and dispatched release.yml on it
 ## When it runs
 
 The `tag` job of the daily release workflow runs it on each push to `main` whose head commit reads as a release, as [checks-release-pr](checks-release-pr.md#running-it-in-ci) shows.
+A package repository needs no `tag` job, since [checks-release-push](checks-release-push.md) tags the release it lands.
 
 ## Related topics
 
 - [checks-release-pr](checks-release-pr.md)
+- [checks-release-push](checks-release-push.md)
 - [checks-release-notes](checks-release-notes.md)