ci: add reusable release-plz workflows, deprecate knope

.github/workflows/ci.yml

@@ -75,7 +75,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        runs-on: [ubuntu-latest, macos-14, windows-latest]
+        runs-on: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.runs-on }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.github/workflows/prepare-prerelease.yml

@@ -1,5 +1,11 @@
 name: Prepare prerelease
 
+# DEPRECATED: use release-plz-prerelease.yml instead.
+# This knope-based workflow still works for callers pinned to a tag, and now
+# also with `GITHUB_TOKEN` alone, but it will be removed in a future breaking
+# release.
+# See the README's "Migrating from knope to release-plz".
+
 # Reusable workflow: cut a release candidate from the branch it is dispatched
 # on, so it can be tested before merging. Callers wire this to
 # workflow_dispatch only; the automatic dry-run-and-release half lives in
@@ -37,13 +43,17 @@ on:
       token:
         description: >-
           Token used to push the prerelease commit and tag and to publish the
-          prerelease. Must be a PAT or app token if the push needs to trigger
-          further workflows, such as a binary build: pushes made with
-          GITHUB_TOKEN do not start new runs.
-        required: true
+          prerelease. Falls back to the job's own token, which is enough here:
+          the prerelease runs all its stages in one workflow and needs no
+          downstream trigger. The branch must accept a push from
+          github-actions.
+        required: false
 
+# Write access, not read: the prerelease pushes a commit and a tag. This caps
+# what the called job's token can do, and `contents: read` here made the
+# `GITHUB_TOKEN` fallback impossible.
 permissions:
-  contents: read
+  contents: write
 
 jobs:
   prepare-prerelease:
@@ -66,7 +76,7 @@ jobs:
           fetch-depth: 0
           # Prerelease the dispatched branch, so its tag lands on that branch.
           ref: ${{ github.ref }}
-          token: ${{ secrets.token }}
+          token: ${{ secrets.token || github.token }}
 
       - name: Install knope
         uses: knope-dev/action@19617851f9f13ab2f27a05989c55efb18aca3675 # v2.1.2
@@ -94,7 +104,7 @@ jobs:
 
       - name: Prerelease
         env:
-          GITHUB_TOKEN: ${{ secrets.token }}
+          GITHUB_TOKEN: ${{ secrets.token || github.token }}
           PRERELEASE_LABEL: ${{ inputs.prerelease-label }}
           KNOPE_WORKFLOW: ${{ inputs.knope-workflow }}
         run: |

.github/workflows/prepare-release.yml

@@ -1,5 +1,11 @@
 name: Prepare release
 
+# DEPRECATED: use release-plz.yml instead.
+# This knope-based workflow needs a PAT or app token to work at all: pushes made
+# with `GITHUB_TOKEN` start no workflow runs. It still works for callers pinned
+# to a tag and will be removed in a future breaking release.
+# See the README's "Migrating from knope to release-plz".
+
 # Reusable workflow: the automatic half of a knope-driven release.
 #
 #   pull_request   dry run, so a PR shows what it would release

.github/workflows/publish-release.yml

@@ -1,5 +1,11 @@
 name: Publish release
 
+# DEPRECATED: use release-plz.yml (set `bin`); its publish job replaces this instead.
+# This knope-based workflow needs a PAT or app token to work at all: pushes made
+# with `GITHUB_TOKEN` start no workflow runs. It still works for callers pinned
+# to a tag and will be removed in a future breaking release.
+# See the README's "Migrating from knope to release-plz".
+
 # Reusable workflow: the second half of a split knope release. The caller's
 # `draft-release` workflow prepared and pushed the version bump; this runs
 # knope's `Release` step once the artifacts to attach exist.

.github/workflows/release-plz-prerelease.yml

@@ -0,0 +1,156 @@
+name: release-plz prerelease
+
+# Reusable workflow: publish a release candidate from the branch it is
+# dispatched on, using only the job's `GITHUB_TOKEN`. Wire it to
+# `workflow_dispatch` only. Replaces `rust-cli-prerelease.yml`.
+#
+# The purpose of this flow is to let consumers use a version of the tool that
+# includes unmerged work, for example to try a branch in another repository's
+# CI before the change lands. It is not a release candidate of the next
+# release: the tag points at the branch head, not at a release PR.
+#
+# release-plz has no prerelease flow: it releases the version in the tree, and
+# its release PR computes the next stable version. So this does not use
+# release-plz to release anything. Instead it
+#
+#   1. builds the branch's binaries as the requested version, applying
+#      `release-plz set-version` in the runner's checkout only;
+#   2. creates a draft GitHub release, attaches the binaries, and publishes it
+#      as a prerelease.
+#
+# Differences from the knope flow, all deliberate:
+# - Nothing is committed or pushed. The tag `<tag-prefix><version>` is created
+#   at the branch's head commit, whose Cargo.toml still carries the old version.
+#   The binaries report the requested version.
+# - The version is an explicit input; nothing computes the next `rc.N`.
+# - No changelog is written, and the prerelease notes are GitHub's generated
+#   notes.
+#
+# The calling job must grant `contents: write`. The release is created as a
+# draft and published only after the binaries are attached, as in
+# release-plz.yml.
+on:
+  workflow_call:
+    inputs:
+      bin:
+        description: Name of the binary to build, as `cargo build -p` expects it.
+        type: string
+        required: true
+      version:
+        description: >-
+          Full prerelease version, e.g. `1.3.0-rc.0`. Must carry a SemVer
+          prerelease suffix, so it can never collide with a stable release.
+        type: string
+        required: true
+      tag-prefix:
+        description: Prefix of the git tag. Must match the stable tags (release-plz's default is `v`).
+        type: string
+        required: false
+        default: v
+      matrix:
+        description: Platform matrix; see rust-cli-build.yml for the default.
+        type: string
+        required: false
+        default: ""
+      toolchain:
+        type: string
+        required: false
+        default: stable
+      artifact-path:
+        description: Directory the build artifacts are gathered into before upload.
+        type: string
+        required: false
+        default: release
+      default-branch:
+        description: Branch that releases through release-plz.yml, and so is refused here.
+        type: string
+        required: false
+        default: main
+    secrets:
+      token:
+        description: Optional PAT or app token, used instead of `GITHUB_TOKEN`.
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      tag: ${{ steps.check.outputs.tag }}
+    steps:
+      - name: Validate the request
+        id: check
+        env:
+          VERSION: ${{ inputs.version }}
+          TAG_PREFIX: ${{ inputs.tag-prefix }}
+          REF: ${{ github.ref }}
+          DEFAULT_BRANCH: ${{ inputs.default-branch }}
+          GH_TOKEN: ${{ secrets.token || github.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          if [[ "${REF}" != refs/heads/* ]]; then
+            echo "::error::Dispatch this from a branch, not ${REF}."
+            exit 1
+          fi
+          if [[ "${REF}" == "refs/heads/${DEFAULT_BRANCH}" ]]; then
+            echo "::error::${DEFAULT_BRANCH} releases through release-plz.yml; dispatch this from the branch you want a release candidate for."
+            exit 1
+          fi
+          # SemVer 2.0.0 with a mandatory prerelease part.
+          re='^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)-([0-9A-Za-z-]+)(\.[0-9A-Za-z-]+)*$'
+          if ! [[ "${VERSION}" =~ ${re} ]]; then
+            echo "::error::'${VERSION}' is not a SemVer prerelease version such as 1.3.0-rc.0."
+            exit 1
+          fi
+          tag="${TAG_PREFIX}${VERSION}"
+          if gh release view "${tag}" --repo "${REPO}" >/dev/null 2>&1; then
+            echo "::error::A release named ${tag} already exists; pick the next version."
+            exit 1
+          fi
+          echo "tag=${tag}" >> "${GITHUB_OUTPUT}"
+
+  build:
+    needs: check
+    uses: rigetti/qcs-gha-infrastructure/.github/workflows/rust-cli-build.yml@v0.4.10
+    with:
+      bin: ${{ inputs.bin }}
+      matrix: ${{ inputs.matrix }}
+      toolchain: ${{ inputs.toolchain }}
+      version: ${{ inputs.version }}
+      # The head of the dispatched branch, which is also what gets tagged.
+      ref: ${{ github.sha }}
+
+  publish:
+    name: publish
+    needs: [check, build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          path: ${{ inputs.artifact-path }}
+          merge-multiple: true
+
+      - name: Create the draft, attach the binaries, publish the prerelease
+        env:
+          GH_TOKEN: ${{ secrets.token || github.token }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ needs.check.outputs.tag }}
+          SHA: ${{ github.sha }}
+          ARTIFACT_PATH: ${{ inputs.artifact-path }}
+        run: |
+          set -euo pipefail
+          ls -l "${ARTIFACT_PATH}"
+          gh release create "${TAG}" --repo "${REPO}" \
+            --draft --prerelease --target "${SHA}" \
+            --title "${TAG}" --generate-notes
+          gh release upload "${TAG}" "${ARTIFACT_PATH}"/* --repo "${REPO}"
+          gh release edit "${TAG}" --repo "${REPO}" --draft=false
+          echo "Published prerelease ${TAG} at ${SHA}."