@avi2dg/checks 0.52.0 → 0.53.0

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)

package/docs/gates/checks-secrets.md

@@ -5,6 +5,7 @@ audience: consumers
 # checks-secrets
 
 `checks-secrets` is the gate that fails a range whose commits add a secret, such as an API token, a private key, a VPN key or a proxy link that carries its credential.
+A private pack adds terms no public file may carry, such as a person's name, an employer's domain, host names and IP ranges.
 
 ## What it checks
 
@@ -39,12 +40,90 @@ These rules do not catch:
 No setting accepts a finding.
 It ignores a repository's `.gitleaks.toml`, its `.gitleaksignore` and every `gitleaks:allow` comment.
 It skips the paths gitleaks' default config skips, such as lockfiles, images and `node_modules/`.
+It scans what a commit adds to its files, and not its message or its author, which [checks-commit-identity](checks-commit-identity.md) judges.
+
+## The private pack
+
+The private pack is a JSON file of terms that lives outside every public repository, and `CHECKS_SECRETS_PACK` names its path.
+The kit ships no pack and no term, so a public repository can run the pack without carrying what it hides.
+With `CHECKS_SECRETS_PACK` unset the gate runs the kit's rules alone, exactly as it does without a pack, and its last line says so.
+With it set the gate adds a rule for each kind of term the pack lists, and fails a range that adds any of them.
+
+Each key is optional, and each holds a list of strings:
+
+| Key | Rule | What it matches |
+| --- | --- | --- |
+| `names` | `private-name` | a person's name form, such as a full name, a handle or a login |
+| `domains` | `private-domain` | an employer's or any other domain, also inside an email address or a subdomain |
+| `hosts` | `private-host` | a host name |
+| `runners` | `private-runner` | a CI runner's name |
+| `ipRanges` | `private-ip-range` | an IPv4 address inside a CIDR range, such as `192.0.2.0/24`, or a single IPv4 address |
+
+A pack with obviously fake terms reads like this:
+
+```json
+{
+  "names": ["Pat Example", "pexample"],
+  "domains": ["employer.example"],
+  "hosts": ["build-01.corp.example"],
+  "runners": ["runner-blue-7"],
+  "ipRanges": ["192.0.2.0/24", "198.51.100.7"]
+}
+```
+
+A term matches in any case, and the spaces inside it match any run of ASCII whitespace or Unicode space separators.
+A term's end that is an ASCII letter, digit or underscore matches only at a word boundary, so `pexample` does not match inside `pexamples`.
+An address matches only as a whole, so `192.0.2.0/24` does not match `1192.0.2.5`.
+An IPv6 range has no key, so a pack lists its prefix under `hosts` as its addresses are written, such as `2001:db8:`.
+The gitleaks default allowlist skips paths such as lockfiles, go.mod and go.sum, images and documents such as PDFs.
+It also skips node_modules and some Go and Ruby vendor paths, so the pack terms are not searched there.
+A lockfile's resolved URLs can carry a private registry host, so keep such a host out of lockfiles, go.mod and go.sum by other means.
+Commit messages are not scanned by the pack, and checks-commit-identity covers only the author, the committer and Co-authored-by trailers.
+
+The gate exits 2, and scans nothing, when `CHECKS_SECRETS_PACK` is set but the pack cannot serve:
+
+- the variable is set to an empty value, as a CI secret that is missing expands
+- the file is missing, unreadable or a directory
+- the file is not JSON or holds a key the table does not name
+- a term is blank or holds a control character, or a range is not IPv4
+- the pack lists no term at all
+
+No report or error prints a matched term text or the pack path, because a public CI log would publish either.
+A finding names its file, its line and its rule, and the description of each pack rule says only which kind of term matched.
+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.
+
+The pack lives where only its owner reads it.
+On a laptop it is a file outside every checkout, and the shell profile exports its path:
+
+```sh
+export CHECKS_SECRETS_PACK="$HOME/.config/checks/secrets-pack.json"
+```
+
+In GitHub Actions a repository or organisation secret holds the JSON, and the job writes it to a file before the gate runs:
+
+```yaml
+- name: write the private pack
+  env:
+    PACK: ${{ secrets.CHECKS_SECRETS_PACK }}
+  run: |
+    printf '%s' "$PACK" > "$RUNNER_TEMP/secrets-pack.json"
+    echo "CHECKS_SECRETS_PACK=$RUNNER_TEMP/secrets-pack.json" >> "$GITHUB_ENV"
+- run: bun run lint
+```
+
+A fork's `pull_request` run gets no secret, so the file is empty and the gate exits 2 rather than pass without the pack.
+Unlike [checks-pr-text](checks-pr-text.md), this gate has no skip: a job that writes the pack from an unset secret exits 2.
+[checks-pr-text](checks-pr-text.md) scans a pull request's title, body and comments with the same pack.
 
 ## What it reads
 
 It reads the commits of the range from git, not the working tree.
 It needs git 2.36 or newer, which diffs a merge against the merge git would make on its own, and it exits 2 on an older git.
 It reads its rules from `src/delivery/gitleaks.toml` in the installed package.
+It reads the path of the private pack from `CHECKS_SECRETS_PACK`.
+It writes the kit's rules and the pack's into one config in a temporary directory it deletes when the scan ends.
 
 It runs the gitleaks release `src/delivery/gitleaks.ts` pins, by the SHA-256 of each platform's archive and of the binary inside it.
 On first use it downloads the archive from the scanner's GitHub release and unpacks the binary into `~/.cache/avi2dg-checks/gitleaks/<version>/`.
@@ -69,7 +148,7 @@ With one it scans that commit alone.
 | --- | --- |
 | 0 | no commit in the range adds a secret |
 | 1 | a commit in the range adds a secret |
-| 2 | a ref does not resolve, or a commit it scans is an octopus merge, or no verified scanner is at hand, or git is older than 2.36, or gitleaks fails |
+| 2 | a ref does not resolve, or a commit it scans is an octopus merge, or no verified scanner is at hand, or git is older than 2.36, or gitleaks fails, or `CHECKS_SECRETS_PACK` is set and the pack cannot serve |
 
 ## Sample output
 
@@ -78,6 +157,15 @@ secrets: the range adds 3 secret(s); put a placeholder such as <private-key> in
   vpn/links.txt:1 proxy-userinfo-link in e19e45c2: A proxy share link that carries its credential before the @, such as vless://, trojan://, socks5:// or wireguard://
   vpn/wg0.conf:2 wireguard-key in e19e45c2: A WireGuard or AmneziaWG private or pre-shared key
   vpn/wg0.conf:7 wireguard-key in e19e45c2: A WireGuard or AmneziaWG private or pre-shared key
+secrets: CHECKS_SECRETS_PACK is unset, so the kit's rules ran without a private pack
+```
+
+With a pack set, a finding of the pack names the kind of term and never the term:
+
+```
+secrets: the range adds 1 secret(s); put a placeholder such as <private-key> in its place in the commit that added it, and rotate any secret that left this machine:
+  docs/setup.md:12 private-domain in 4f1c09ab: A domain the private pack lists
+secrets: the kit's rules and the private pack CHECKS_SECRETS_PACK names ran
 ```
 
 The report never prints a secret.
@@ -90,4 +178,5 @@ A local `bun run lint` runs it over the commits the branch adds, so it fails bef
 ## Related topics
 
 - [checks-lint](checks-lint.md)
+- [checks-pr-text](checks-pr-text.md)
 - [Why it is shaped this way](../design.md)