@ebalzan/ci 1.0.0 → 2.0.0

package/README.md

@@ -0,0 +1,281 @@
+# @ebalzan/ci
+
+One set of CI/CD rules for all your GitHub repos:
+
+- **Composite GitHub Actions**: they open work and release PRs with AI descriptions, check every PR, and cut semver releases from Conventional Commits.
+- **A CLI** (`ebalzan-ci`): it onboards a repo and keeps its Actions variables, secrets, settings and branch rulesets in sync.
+- **A commitlint `commit-msg` hook** and a **Renovate preset** for the shared tooling.
+
+Repos call the actions pinned to a major tag (`ebalzan/ci/actions/<name>@v2`), so fixes reach every repo with each release, with nothing to copy around.
+
+## The git flow
+
+```mermaid
+flowchart LR
+  F["feat/… fix/… branch"] -- "work PR<br/>squash merge" --> D[dev]
+  D -- "release PR<br/>ship label = fast-forward" --> M[main]
+  M -- "tag vX.Y.Z<br/>GitHub Release" --> R((deploy))
+```
+
+There are three kinds of branch, and history stays **linear**: no merge commits anywhere.
+
+| Branch                 | Lives       | Gets changes by                                  | Rewritten?                                 |
+| ---------------------- | ----------- | ------------------------------------------------ | ------------------------------------------ |
+| `<type>/<description>` | hours, days | your commits                                     | yes, by you (rebase, `--force-with-lease`) |
+| `dev`                  | forever     | squash-merged work PRs                           | never                                      |
+| `main`                 | forever     | the Release workflow fast-forwarding it to `dev` | never                                      |
+
+The two hops merge differently:
+
+- **work branch → `dev`: squash merge.** All of a branch's commits become one commit on `dev`, titled after the PR.
+- **`dev` → `main`: fast-forward.** `main` moves forward to `dev`'s commits as they are. It gets no new commits and no merge commit.
+
+What happens to the commits:
+
+```text
+1. Work on a branch: as many commits as you like.
+
+   feat/search-filters        a ── b ── c
+                             /
+   dev, main      ── X ────┘
+
+2. Squash-merge the work PR: a, b and c become ONE new commit S on dev.
+   The branch is deleted; main has not moved.
+
+   dev            ── X ── S                   S = feat: add search filters (#12)
+   main           ── X
+
+3. More work PRs land on dev the same way, one commit each.
+
+   dev            ── X ── S ── T              T = fix: empty results (#13)
+   main           ── X
+
+4. Add the `ship` label to the release PR: the Release workflow adds the
+   release commit R, then moves main AND dev forward to it. Nothing is merged
+   or rewritten: main gets dev's exact commits, with the same SHAs.
+
+   dev, main      ── X ── S ── T ── R         R = chore(release): 1.4.0, tagged v1.4.0
+```
+
+After step 4, `dev` and `main` point at the same commit, so the next work branch starts from the release.
+
+### 1. Work on a branch
+
+Branch off `dev`. The branch name is `<type>/<description>`, where `<type>` is one of the [work types](#work-types):
+
+```sh
+git switch dev && git pull
+git switch -c feat/search-filters
+git commit -m "feat: add search filters"     # Conventional Commits, checked by the hook
+git push -u origin feat/search-filters
+```
+
+**Auto PR** opens a PR into `dev` on that push. It sets:
+
+- the title: the first commit whose type is the branch's type;
+- the type label, with you as the assignee;
+- the milestone and the project board, when the repo configures them;
+- an AI-written description.
+
+It opens the PR as a draft and marks it ready for review once all of that is done.
+
+While you work, keep the branch on top of `dev` by **rebasing, never merging**. The branch is yours, so rewriting it is fine:
+
+```sh
+git fetch && git rebase origin/dev
+git push --force-with-lease
+```
+
+Optionally, tidy the commits before review: commit fixes with `git commit --fixup <sha>`, then fold them in with `git rebase -i --autosquash origin/dev`.
+
+### 2. Merge the work PR into dev (squash)
+
+**PR Checks** (`pr-check / Work PR`) must pass:
+
+- the PR title and every commit follow Conventional Commits;
+- the base is `dev`;
+- the branch is `<type>/…`, and the title's type matches the branch's type;
+- it has the type label and an assignee, and the author is the owner, a member or a collaborator;
+- it has the milestone and is on the board, when those are set;
+- it has a description.
+
+It warns about large PRs, breaking changes and a branch that is behind `dev`.
+
+Then **squash-merge** it. The PR title becomes the one commit on `dev`, and that commit is what drives the next version.
+
+### 3. The release PR (dev → main)
+
+Every push to `dev` makes **Auto PR** open or update **the** release PR, `dev` → `main`:
+
+- **Title:** the release it will cut, e.g. `feat: release v1.4.0`. git-cliff computes it from the commits since the last tag.
+- **Description:** an AI summary above the changelog.
+- **Label:** `release`.
+
+Its check (`pr-check / Release PR`) holds it to the computed title. It also requires the label, an assignee, the milestone and board when they're set, and a description. Finally, `dev` must contain `main` and must not contain a merge commit.
+
+### 4. Ship it with the `ship` label, never the merge button
+
+When the release PR's check passes, **add the `ship` label**. The **Release** workflow then does this:
+
+1. **Verify.** `dev` is still the PR's head, `main` fast-forwards to it, there's no merge commit, and the PR check passed. If the check is still running, it waits.
+2. **Version and tag.** It recomputes the title and requires it to equal the PR's. In a Node repo it commits `chore(release): X.Y.Z` to bump `package.json`. Then it pushes **`main` and `dev` to that same commit**, along with `vX.Y.Z` and the moving major tag `vX`, in **one atomic push**.
+3. **Publish.** It creates the GitHub Release `vX.Y.Z`, using the PR's description as the notes.
+4. **Deploy.** It calls the repo's own `.github/workflows/deploy.yml` with the new tag.
+
+GitHub then marks the release PR as merged. `main` got exactly `dev`'s commits, with the same SHAs. `dev` and `main` end on the same commit, so the next release starts clean and no open work branch is disturbed.
+
+If something moved in the meantime, nothing is pushed: remove the label and add it again. If someone merges the release PR with a GitHub button anyway, the job fails and prints the command that puts `main` back. Squash and rebase both rewrite `dev`'s commits, which would make `main` and `dev` diverge.
+
+> There's no hotfix path straight to `main`. A fix goes `fix/…` → `dev` → release PR like any other change. `main` only ever moves through a release.
+
+## Work types
+
+[`config/types.json`](config/types.json) is the only place a type is defined. Each type works as a branch prefix, a Conventional Commit and PR-title type, and a PR label.
+
+| Type                                                                               | Release |
+| ---------------------------------------------------------------------------------- | ------- |
+| `feat`                                                                             | minor   |
+| `fix`, `refact`, `perf`, `revert`, `build`, `ci`, `docs`, `test`, `style`, `chore` | patch   |
+
+A `!` after the type (`feat!: …`), or a `BREAKING CHANGE:` footer, makes any type a **major** release, from 0.x too. A repo with no tag yet starts at `v0.1.0`. Note that the type is `refact`, not `refactor`.
+
+## Branch protection
+
+`ebalzan-ci sync` applies these rulesets ([`config/rulesets/`](config/rulesets)) and repository settings ([`config/repo-settings.json`](config/repo-settings.json)):
+
+| Ruleset                            | Default  | Effect                                                                                     |
+| ---------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
+| `ci: protect main`                 | active   | no deletion, no force-push, linear history                                                 |
+| `ci: protect dev`                  | active   | no deletion, no force-push, linear history                                                 |
+| `ci: require pull request`         | disabled | `dev` changes only via a squash-merged work PR that passed `pr-check / Work PR`            |
+| `ci: require release pull request` | disabled | nobody but GitHub Actions can update `main`, so the release PR's merge buttons are blocked |
+
+**Settings:** squash merge only, with the PR title as the commit title. Merge commits and rebase merges are off. Head branches are deleted on merge.
+
+The two disabled rulesets need the GitHub Actions app to be able to bypass them, because the release pushes with `GITHUB_TOKEN`. Enable one per repo with `.github/rulesets/<file>.json` containing `{ "enforcement": "active" }`, run one release, and confirm it went through.
+
+## Getting started
+
+Requirements:
+
+- Node >= 22.12;
+- [`gh`](https://cli.github.com), authenticated with admin rights on the repo.
+
+### 1. Shared secrets (once)
+
+```sh
+cp config/secrets.env.example config/secrets.env   # in a checkout of this repo, or ~/.config/ebalzan-ci/
+```
+
+| Secret              | Used for                                                                                                                     |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `ANTHROPIC_API_KEY` | the AI descriptions of work and release PRs. Without it, PRs keep the commit list or the changelog.                          |
+| `GH_PROJECT_TOKEN`  | a **classic** PAT (`repo` + `project`), so the PRs Auto PR opens trigger PR Checks and can reach a user-owned Projects board |
+
+### 2. Onboard a repo
+
+In the repo's checkout:
+
+```sh
+npx @ebalzan/ci onboard
+```
+
+`onboard` does the following:
+
+1. Creates the branch `ci/onboard-ebalzan-ci` from `dev`.
+2. Writes the workflows (`auto-pr.yml`, `pr-checks.yml`, `release.yml`, and a starter `deploy.yml`), plus `.github/actions.env` and `renovate.json`.
+3. For a Node repo, adds the husky `commit-msg` hook, the `@ebalzan/ci` and `husky` devDependencies, and the shared Prettier and ESLint config.
+4. Gitignores the secrets files and commits everything.
+5. Creates `dev` if it's missing, runs `sync`, and pushes.
+
+Auto PR then opens the onboarding PR into `dev`. Squash-merge it. Run `npx @ebalzan/ci onboard --help` for the options (`--ref`, `--runs-on`, `--force FILE`, `--no-npm`, `--no-push`, `--dry-run`, …).
+
+Then:
+
+- add the repo's own build, test and lint jobs to `.github/workflows/pr-checks.yml` (it has a commented example);
+- put what ships a release into `.github/workflows/deploy.yml`. It's the repo's own file, and `onboard` never overwrites it.
+
+### 3. Keep it in sync
+
+```sh
+npx @ebalzan/ci sync --dry-run   # see the plan
+npx @ebalzan/ci sync
+```
+
+Each setting comes from two layers, and the repo's own value wins:
+
+| What                | Shared (every repo)           | The repo's own                     |
+| ------------------- | ----------------------------- | ---------------------------------- |
+| variables           | `config/actions.env`          | `.github/actions.env`              |
+| secrets             | `<secrets>/secrets.env`       | `.github/secrets.env` (gitignored) |
+| environment secrets | `<secrets>/secrets.<env>.env` | `.github/secrets.<env>.env`        |
+| repository settings | `config/repo-settings.json`   | `.github/repo-settings.json`       |
+| branch rulesets     | `config/rulesets/<file>.json` | `.github/rulesets/<file>.json`     |
+
+How the layers combine:
+
+- **JSON files** deep-merge.
+- **Shared variables** are read by the actions at run time, never copied onto repos, so changing one only needs a release of this package.
+- **Removals:** `--prune` deletes what no file defines.
+
+## Configuration
+
+Repo variables (`.github/actions.env`) or the shared `config/actions.env`:
+
+| Variable                                       | Default        | Effect                                                        |
+| ---------------------------------------------- | -------------- | ------------------------------------------------------------- |
+| `AUTO_PROJECT_NUMBER`                          | none           | the Projects (v2) board every PR must be on                   |
+| `AUTO_PROJECT_OWNER`                           | the repo owner | that board's owner                                            |
+| `AUTO_MILESTONE_TITLE`                         | none           | the milestone every PR must have                              |
+| `AUTO_MAX_CHANGED_LINES`                       | `500`          | work PRs over this get a size warning                         |
+| `AUTO_DESCRIBE_MODEL` / `AUTO_DESCRIBE_EFFORT` | shared         | the Claude model, and its effort, that writes PR descriptions |
+
+## What's inside
+
+| Path                                | What                                                                              |
+| ----------------------------------- | --------------------------------------------------------------------------------- |
+| `actions/auto-pr`                   | opens or updates the work PR of a branch, or the release PR of `dev`              |
+| `actions/pr-checks`                 | commitlint on the title and commits, then Danger rules for the PR's kind          |
+| `actions/release`                   | verifies, fast-forwards, tags and publishes the release on the `ship` label       |
+| `bin/`, `lib/`                      | the `ebalzan-ci` CLI: `onboard`, `sync`, `commit-msg`                             |
+| `templates/`                        | the files `onboard` writes into a repo                                            |
+| `config/`                           | types, shared variables, repo settings, rulesets, the git-cliff config            |
+| `renovate/tooling.json`             | Renovate preset for the shared tooling (`github>ebalzan/ci//renovate/tooling#v2`) |
+| `commitlint.config.mjs`, `scripts/` | the commit rules, the release title and the changelog                             |
+
+## Upgrading from v1
+
+In v1, the release PR was merged with a merge commit. In v2 it ships with the `ship` label (a fast-forward). Repos pinned to `@v1` keep working until they move. Per repo, **between two releases**:
+
+1. If `git rev-list --merges origin/main..origin/dev` prints anything (an unreleased `Merge branch 'main' into dev`), rebase it away once, before syncing:
+   `git switch dev && git rebase origin/main && git push --force-with-lease`.
+2. Refresh the workflows. `release.yml` is required; `deploy.yml` is kept:
+   ```sh
+   npx @ebalzan/ci@2 onboard --ref v2 \
+     --force .github/workflows/release.yml --force .github/workflows/pr-checks.yml \
+     --force .github/workflows/auto-pr.yml --force renovate.json
+   ```
+3. Apply the new settings and rulesets with `npx @ebalzan/ci@2 sync`. Drop any `allow_merge_commit: true` override in `.github/repo-settings.json`.
+4. Squash-merge the onboarding PR into `dev`, then release by adding the `ship` label to the release PR.
+
+Do steps 2–4 together. The old `release.yml` expects a merge commit, and step 3 turns merge commits off.
+
+## Developing this repo
+
+```sh
+npm ci
+npm run check          # bash -n / node --check on every script
+npm run lint           # ESLint, zero warnings
+npm run format:check   # Prettier
+npm test               # node:test, on throwaway git repos with a stubbed gh
+```
+
+The same flow applies here: work branches squash into `dev`. This repo has no workflows of its own, so release it by hand, with a fast-forward rather than a merge commit:
+
+```sh
+git switch main && git merge --ff-only dev && git push
+```
+
+## License
+
+[MIT](LICENSE)

package/config/repo-settings.json

@@ -1,12 +1,10 @@
 {
-  "$comment": "Repository settings every managed repo gets (PATCH /repos/{owner}/{repo}). A repo overrides any key in its own .github/repo-settings.json. Keys starting with $ are documentation and are never sent. Work PRs are squash-merged into dev (the PR title becomes the commit); the dev → main release PR is merged with a merge commit (GitHub's default title, which commitlint and git-cliff skip). Rebase merges are off: they rewrite commits.",
+  "$comment": "Repository settings every managed repo gets (PATCH /repos/{owner}/{repo}). A repo overrides any key in its own .github/repo-settings.json. Keys starting with $ are documentation and are never sent. History is linear, with no merge commits: work PRs are squash-merged into dev (the PR title becomes the commit); the dev → main release PR is never merged with a button — its `ship` label makes the Release workflow fast-forward main to dev. Merge commits and rebase merges are off: rebase rewrites dev's commits, so main and dev would diverge.",
   "allow_squash_merge": true,
-  "allow_merge_commit": true,
+  "allow_merge_commit": false,
   "allow_rebase_merge": false,
   "squash_merge_commit_title": "PR_TITLE",
   "squash_merge_commit_message": "COMMIT_MESSAGES",
-  "merge_commit_title": "MERGE_MESSAGE",
-  "merge_commit_message": "PR_TITLE",
   "delete_branch_on_merge": true,
   "allow_update_branch": true
 }

package/config/rulesets/protect-dev.json

@@ -1,10 +1,14 @@
 {
-  "$comment": "dev is the integration branch: it cannot be deleted or force-pushed. The Release workflow only fast-forwards it (or merges main into it), so nothing in the pipeline needs a bypass.",
+  "$comment": "dev is the integration branch: it cannot be deleted or force-pushed, and its history stays linear (main fast-forwards to it). Work PRs squash into it; the Release workflow only fast-forwards it to the release commit, so nothing in the pipeline needs a bypass.",
   "name": "ci: protect dev",
   "target": "branch",
   "enforcement": "active",
   "conditions": {
     "ref_name": { "include": ["refs/heads/dev"], "exclude": [] }
   },
-  "rules": [{ "type": "deletion" }, { "type": "non_fast_forward" }]
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" },
+    { "type": "required_linear_history" }
+  ]
 }

package/config/rulesets/protect-main.json

@@ -1,10 +1,14 @@
 {
-  "$comment": "main is the release branch: it cannot be deleted or force-pushed. The Release workflow only fast-forwards it with the `chore(release): X.Y.Z` commit, so nothing in the pipeline needs a bypass.",
+  "$comment": "main is the release branch: it cannot be deleted or force-pushed, and its history stays linear. The Release workflow only fast-forwards it to dev (plus the `chore(release): X.Y.Z` commit), so nothing in the pipeline needs a bypass.",
   "name": "ci: protect main",
   "target": "branch",
   "enforcement": "active",
   "conditions": {
     "ref_name": { "include": ["refs/heads/main"], "exclude": [] }
   },
-  "rules": [{ "type": "deletion" }, { "type": "non_fast_forward" }]
+  "rules": [
+    { "type": "deletion" },
+    { "type": "non_fast_forward" },
+    { "type": "required_linear_history" }
+  ]
 }

package/config/rulesets/require-pull-request.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Changes reach dev only through a squash-merged work PR whose 'pr-check / Work PR' check passed — its title becomes the one commit on dev. main is require-release-pr.json's. DISABLED by default: the Release workflow brings dev up to main with GITHUB_TOKEN (a fast-forward, or a merge of main when work landed meanwhile), so the GitHub Actions app (Integration 15368) must be able to bypass it. Enable it per repo with .github/rulesets/require-pull-request.json containing {\"enforcement\": \"active\"}, run one release, and confirm it went through.",
+  "$comment": "Changes reach dev only through a squash-merged work PR whose 'pr-check / Work PR' check passed — its title becomes the one commit on dev. main is require-release-pr.json's. DISABLED by default: the Release workflow fast-forwards dev to the release commit with GITHUB_TOKEN, so the GitHub Actions app (Integration 15368) must be able to bypass it. Enable it per repo with .github/rulesets/require-pull-request.json containing {\"enforcement\": \"active\"}, run one release, and confirm it went through.",
   "name": "ci: require pull request",
   "target": "branch",
   "enforcement": "disabled",

package/config/rulesets/require-release-pr.json

@@ -1,33 +1,11 @@
 {
-  "$comment": "Changes reach main only through the dev → main release PR, merged with a merge commit after 'pr-check / Release PR' passed: dev's commits reach main unchanged, so dev catches up without a force-push. The Release workflow fails on a squash or rebase merge; this ruleset hides those buttons. DISABLED by default: the Release workflow pushes the `chore(release): X.Y.Z` commit to main with GITHUB_TOKEN, so the GitHub Actions app (Integration 15368) must be able to bypass it. Enable it per repo with .github/rulesets/require-release-pr.json containing {\"enforcement\": \"active\"}, run one release, and confirm it went through.",
+  "$comment": "main moves only through the Release workflow: the release PR's `ship` label makes it fast-forward main to dev after 'pr-check / Release PR' passed (the workflow checks it). This ruleset restricts updates to its bypass list — GitHub Actions only — so nobody can merge into or push to main, and the release PR's merge buttons stay blocked (squash and rebase would rewrite dev's commits). In an emergency, an admin disables it. DISABLED by default: the Release workflow pushes main with GITHUB_TOKEN, so the GitHub Actions app (Integration 15368) must be able to bypass it. Enable it per repo with .github/rulesets/require-release-pr.json containing {\"enforcement\": \"active\"}, run one release, and confirm it went through.",
   "name": "ci: require release pull request",
   "target": "branch",
   "enforcement": "disabled",
   "conditions": {
     "ref_name": { "include": ["refs/heads/main"], "exclude": [] }
   },
-  "bypass_actors": [
-    { "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" },
-    { "actor_id": 15368, "actor_type": "Integration", "bypass_mode": "always" }
-  ],
-  "rules": [
-    {
-      "type": "pull_request",
-      "parameters": {
-        "required_approving_review_count": 0,
-        "dismiss_stale_reviews_on_push": false,
-        "require_code_owner_review": false,
-        "require_last_push_approval": false,
-        "required_review_thread_resolution": false,
-        "allowed_merge_methods": ["merge"]
-      }
-    },
-    {
-      "type": "required_status_checks",
-      "parameters": {
-        "strict_required_status_checks_policy": false,
-        "required_status_checks": [{ "context": "pr-check / Release PR" }]
-      }
-    }
-  ]
+  "bypass_actors": [{ "actor_id": 15368, "actor_type": "Integration", "bypass_mode": "always" }],
+  "rules": [{ "type": "update", "parameters": { "update_allows_fetch_and_merge": false } }]
 }

package/lib/onboard.mjs

@@ -508,6 +508,8 @@ async function run(opts) {
   info('     commented example).')
   if (tsconfigNote) info(`  ·  ${tsconfigNote}`)
   info('  3. Squash-merge the PR: the dev → main release PR opens.')
+  info('  4. Once its check passes, add the `ship` label to release: main fast-forwards')
+  info('     to dev. Never merge the release PR with a button.')
   return 0
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ebalzan/ci",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "One set of CI/CD rules for all your GitHub repos: reusable workflows (auto work and release PRs with AI descriptions, PR checks, semver releases), a CLI that syncs Actions config, repo settings and branch rulesets, and a commitlint commit-msg hook.",
   "keywords": [
     "github-actions",

package/templates/.github/workflows/deploy.yml

@@ -11,7 +11,8 @@
 #
 # The `production` environment: required reviewers and environment secrets
 # work. Do not limit it to the main branch: a release's run has the ref
-# refs/pull/<n>/merge (it starts from the merged PR), so it would be refused.
+# refs/pull/<n>/merge (it starts from the release PR's event), so it would be
+# refused.
 # Generated by `ebalzan-ci onboard`, which never overwrites it (not even with
 # --force): changes here are yours to keep.
 # =============================================================================

package/templates/.github/workflows/release.yml

@@ -1,36 +1,42 @@
 # =============================================================================
 # Release — runs __CI_REPO__'s release action.
 #
-# Runs when a PR into main is closed; the `release` job runs only when it is
-# the dev → main release PR and it was merged (with a merge commit). Merging a
-# work PR into dev never runs it. The release: the version from the
-# Conventional Commits since the last tag, package.json bumped when there is
-# one, the vX.Y.Z tag, the GitHub Release (the PR's description as notes), and
-# dev brought up to main.
+# The dev → main release PR is never merged with a GitHub button. Once its
+# check passes, add the `ship` label: the `release` job fast-forwards main to
+# dev — the same commits and SHAs, no merge commit — and GitHub marks the PR
+# merged. The release: the version from the Conventional Commits since the
+# last tag, package.json bumped when there is one, the vX.Y.Z tag, the GitHub
+# Release (the PR's description as notes), and main and dev on the release
+# commit. Merging a work PR into dev never runs it.
 #
-# Then `deploy` hands the new tag to deploy.yml — this repo's own file, where
-# what ships the release lives. Generated by `ebalzan-ci onboard`; the release
-# logic lives in the action (it follows __CI_REF__). Keep deploying out of this
-# file.
+# When the release PR is merged with a button anyway (squash or rebase rewrite
+# dev's commits), the same job fails on the `closed` event with how to put main
+# back. Then `deploy` hands the new tag to deploy.yml — this repo's own file,
+# where what ships the release lives. Generated by `ebalzan-ci onboard`; the
+# release logic lives in the action (it follows __CI_REF__). Keep deploying out
+# of this file.
 # =============================================================================
 name: Release
 
 on:
   pull_request:
-    types: [closed]
+    types: [labeled, closed]
     branches: ['main']
 
 permissions:
   contents: write
   pull-requests: read
+  checks: read
 
 jobs:
   release:
     name: Version, tag and publish
     if: >-
-      ${{ github.event.pull_request.merged
-      && github.event.pull_request.head.ref == 'dev'
-      && github.event.pull_request.head.repo.full_name == github.repository }}
+      ${{ github.event.pull_request.head.ref == 'dev'
+      && github.event.pull_request.head.repo.full_name == github.repository
+      && ((github.event.action == 'labeled' && github.event.label.name == 'ship'
+           && github.event.pull_request.state == 'open')
+          || (github.event.action == 'closed' && github.event.pull_request.merged)) }}
     runs-on: __RUNS_ON__
     # Queued, never cancelled: a run cut short could tag without a Release.
     concurrency:
@@ -43,11 +49,11 @@ jobs:
       tag: ${{ steps.release.outputs.tag }}
       sha: ${{ steps.release.outputs.sha }}
     steps:
-      # The merge commit, with full history and the tags: git-cliff computes the
+      # The PR's head, with full history and the tags: git-cliff computes the
       # version from them. Credentials stay: the job pushes main and dev.
       - uses: actions/checkout@v4
         with:
-          ref: ${{ github.event.pull_request.merge_commit_sha }}
+          ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 0
 
       - uses: actions/setup-node@v4
@@ -56,8 +62,6 @@ jobs:
 
       - id: release
         uses: __CI_REPO__/actions/release@__CI_REF__
-        with:
-          dev-token: ${{ secrets.GH_PROJECT_TOKEN }}
 
   deploy:
     needs: release