Cut releases from CI and publish the ghcup channel from a branch

Set up how releases are made. Nothing has been released yet; the repo has no
tags.

A release is cut from Actions -> CI -> Run workflow with release_version set to
the version to release and `publish` ticked. CI builds and tests every platform
and only then tags the revision, publishes the bindists as a GitHub Release and
updates the ghcup channel. Leaving `publish` off rehearses all of it without
tagging or publishing anything.

Tags are produced by CI, never consumed by it, so a v* tag only ever exists for
a revision that built and passed everywhere, and an abandoned attempt leaves
nothing behind but a red run. The v* push trigger is dropped accordingly.

- plinth-build.sh: add RELEASE_VERSION, which rewrites configure.ac's base
  version to the full four-component version and passes RELEASE=YES to
  configure, so the compiler reports exactly the released version instead of
  <base>.<date>. See Note [Release versioning]. The counter lives in the
  release request rather than in configure.ac: a committed four-component base
  would make every later snapshot build five components (9.6.166.1.20260803),
  one more than the tools accept. The value handed to configure is always
  spelled out, so this script's own RELEASE (release flavour) can never be
  mistaken for configure's RELEASE (version stamping). The build aborts if the
  compiler it produced does not report the requested version.
- ci.yml: add the release-precheck job, which rejects an empty version, a
  version that does not extend configure.ac, or one already released -- in
  seconds, rather than after a full matrix build. Verify every bindist tarball
  is named for the released version before generating the channel.
- ci.yml: gate the release job on the plinth-test-* suites as well as the ghcup
  install tests. It depended only on the latter, so a release could have
  shipped a compiler whose test suite had failed.
- ci.yml: publish the ghcup channel to a dedicated orphan `ghcup-channel`
  branch rather than to gh-pages, served from raw.githubusercontent.com (where
  ghcup fetches its own metadata too). Publishing is then a plain git push,
  with no build or deploy step behind it, and the branch is CI's alone, so a
  release cannot conflict with anything else being pushed. The branch is
  created on the first release, so there is nothing to set up by hand.
- configure.ac: document that the version here stays at three components.
- README.md: the new channel URL, the RELEASE_VERSION knob, and how to cut a
  release.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: hsyl20

.github/workflows/ci.yml

@@ -5,19 +5,80 @@ on:
     types: [opened, synchronize]
   push:
     branches: [master, ghc-9.6-plinth]
-    # Pushing a v* tag builds every platform (as on a branch push) and then the
-    # `release` job publishes a GitHub Release + updates the ghcup channel. See
-    # Note [ghcup release channel] on the release job below.
-    tags: ['v*']
+  # Releases are cut from here: run the workflow with a release_version to build
+  # and test that version, and tick `publish` to have the release job tag it and
+  # publish it once everything has passed. See Note [ghcup release channel].
   workflow_dispatch:
+    inputs:
+      release_version:
+        description: >-
+          Build as a release stamped with this version (e.g. 9.6.166.1) instead
+          of the usual dated snapshot version. Leave empty for an ordinary build.
+        required: false
+        default: ''
+      publish:
+        description: >-
+          Tag and publish that version once every build and test job has passed.
+          Leave off to rehearse a release without publishing anything.
+        type: boolean
+        required: false
+        default: false
 
 # Least-privilege GITHUB_TOKEN: jobs only check out code (contents: read).
 # Submodules use a dedicated SSH key and artifacts use the Actions runtime
 # token, so no write scopes are needed.
 permissions:
   contents: read
 
+env:
+  # The version being released ("9.6.166.1", or "v9.6.166.1" -- the steps below
+  # strip the "v"), empty on ordinary pushes and PRs. It is passed to
+  # plinth-build.sh as RELEASE_VERSION, which stamps the compiler with exactly
+  # that version instead of the usual <base>.<date>. See Note [Release
+  # versioning] in plinth-build.sh.
+  REQUESTED_VERSION: ${{ github.event.inputs.release_version || '' }}
+
 jobs:
+  # Reject an unreleasable request in seconds instead of after a full matrix
+  # build. The release job repeats none of this: it inherits the verdict by
+  # depending on this job. See Note [ghcup release channel].
+  release-precheck:
+    name: release-precheck
+    if: ${{ inputs.publish }}
+    runs-on: ubuntu-latest
+    steps:
+
+    - uses: actions/checkout@v4
+      with:
+        submodules: false
+
+    - name: Check the requested release version
+      run: |
+        set -eu
+        VERSION="${REQUESTED_VERSION#v}"
+        if [ -z "$VERSION" ]; then
+          echo "error: publish was requested without a release_version"
+          exit 1
+        fi
+        # The same rule plinth-build.sh applies when stamping the compiler, so a
+        # version it would reject never reaches the build. See Note [Release
+        # versioning] there.
+        BASE_VERSION=$(sed -n 's/^AC_INIT(\[[^]]*\], *\[\([^]]*\)\].*/\1/p' configure.ac)
+        case "$VERSION" in
+          "$BASE_VERSION"|"$BASE_VERSION".*) ;;
+          *)
+            echo "error: $VERSION does not extend the version in configure.ac ($BASE_VERSION)"
+            exit 1
+            ;;
+        esac
+        # Tags are created by the release job, so an existing one means this
+        # version was already released.
+        if git ls-remote --exit-code --tags origin "refs/tags/v$VERSION" >/dev/null 2>&1; then
+          echo "error: v$VERSION is already released"
+          exit 1
+        fi
+        echo "releasing $VERSION from $GITHUB_REF_NAME ($GITHUB_SHA)"
+
   plinth-build-linux:
     name: plinth-build / ${{ matrix.os }} / ghc ${{ matrix.ghc }}
     runs-on: ${{ matrix.os }}
@@ -41,8 +102,10 @@ jobs:
 
     # BINDIST=1 produces the fixed-up uplc-ghc bindist (+ .tar.xz archive) while
     # keeping the lean dev flavour. The plinth-test job consumes that archive.
+    # RELEASE_VERSION is empty except on a release build, where it pins the
+    # version; see Note [Release versioning] in plinth-build.sh.
     - name: Build uplc-ghc bindist
-      run: BINDIST=1 ./plinth-build.sh
+      run: RELEASE_VERSION="${REQUESTED_VERSION#v}" BINDIST=1 ./plinth-build.sh
 
     - name: Upload uplc-ghc bindist
       uses: actions/upload-artifact@v4
@@ -195,6 +258,7 @@ jobs:
         docker run --rm \
           -v "$GITHUB_WORKSPACE:/workspace" -w /workspace \
           -e BINDIST=1 -e LANG=C.UTF-8 -e LC_ALL=C.UTF-8 \
+          -e RELEASE_VERSION="${REQUESTED_VERSION#v}" \
           alpine:3.20 sh -c '
             set -eux
             . ./.github/alpine-setup.sh
@@ -364,7 +428,7 @@ jobs:
     # BINDIST=1 produces the fixed-up uplc-ghc bindist (+ .tar.xz archive); the
     # plinth-test-windows job consumes that archive instead of rebuilding.
     - name: Build uplc-ghc bindist
-      run: BINDIST=1 ./plinth-build.sh
+      run: RELEASE_VERSION="${REQUESTED_VERSION#v}" BINDIST=1 ./plinth-build.sh
 
     - name: Upload uplc-ghc bindist
       uses: actions/upload-artifact@v4
@@ -523,7 +587,7 @@ jobs:
     # BINDIST=1 produces the fixed-up uplc-ghc bindist (+ .tar.xz archive); the
     # plinth-test-macos job consumes that archive instead of rebuilding.
     - name: Build uplc-ghc bindist
-      run: BINDIST=1 ./plinth-build.sh
+      run: RELEASE_VERSION="${REQUESTED_VERSION#v}" BINDIST=1 ./plinth-build.sh
 
     - name: Upload uplc-ghc bindist
       uses: actions/upload-artifact@v4
@@ -798,37 +862,50 @@ jobs:
 
   # Note [ghcup release channel]
   # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-  # On a v* tag, publish the per-platform bindists as a GitHub Release and
-  # (re)generate the ghcup channel metadata on the gh-pages branch. uplc-ghc is
-  # distributed as a custom third-party ghcup tool named `plinth`, installable
-  # with a stock ghcup >= 0.2.1.0 (installer DSL). Users then run:
+  # Once every build and test job has passed, tag the revision, publish the
+  # per-platform bindists as a GitHub Release and (re)generate the ghcup channel
+  # metadata on the ghcup-channel branch (see Note [Tagging a release] below).
+  # uplc-ghc is distributed as a custom third-party ghcup tool named `plinth`,
+  # installable with a stock ghcup >= 0.2.1.0 (installer DSL). Users then run:
   #   ghcup config add-release-channel \
-  #     https://input-output-hk.github.io/ghc-plinth/ghcup-plinth.yaml
+  #     https://raw.githubusercontent.com/input-output-hk/ghc-plinth/ghcup-channel/ghcup-plinth.yaml
   #   ghcup install plinth <version>
   #
-  # The generator (generate-ghcup-metadata.py) accumulates every released
-  # version into gh-pages/ghcup-plinth.versions.json and re-emits the channel
-  # YAML, so old versions stay installable. Before publishing, we validate the
-  # metadata end-to-end by installing plinth from a file:// copy of it (real
-  # download + configure + make + symlink), decoupled from the not-yet-public
-  # release URLs.
+  # The channel lives on its own orphan branch, served straight from
+  # raw.githubusercontent.com (which is also where ghcup fetches its own
+  # metadata). Publishing is then a plain git push, and the branch is CI's alone,
+  # so a release can never conflict with anything else being pushed.
+  # raw.githubusercontent.com caches for 5 minutes (max-age=300), so a fresh
+  # release can take that long to become visible to ghcup.
+  #
+  # The generator (generate-ghcup-metadata.py) accumulates every released version
+  # into ghcup-plinth.versions.json on that branch and re-emits the channel YAML,
+  # so old versions stay installable. Before publishing, we validate the metadata
+  # end-to-end by installing plinth from a file:// copy of it (real download +
+  # configure + make + symlink), decoupled from the not-yet-public release URLs.
   release:
     name: release / ghcup channel
-    if: startsWith(github.ref, 'refs/tags/')
-    # Gate publishing on the per-platform ghcup install tests (which transitively
-    # require the build jobs and their uploaded bindist artifacts).
+    if: ${{ inputs.publish }}
+    # Gate publishing on everything that exercises the bindists: the ghcup
+    # install tests and the Plinth test suites, on every platform. Both sets
+    # transitively require the build jobs and their uploaded artifacts, so the
+    # builds don't need listing here. Without the plinth-test-* jobs a release
+    # could ship a compiler whose test suite failed.
     needs:
+      - release-precheck
       - plinth-ghcup-test-linux
       - plinth-ghcup-test-linux-musl
       - plinth-ghcup-test-windows
       - plinth-ghcup-test-macos
+      - plinth-test-linux
+      - plinth-test-linux-musl
+      - plinth-test-windows
+      - plinth-test-macos
     runs-on: ubuntu-latest
-    # Overrides the top-level `contents: read`: this job creates a Release and
-    # pushes the regenerated channel to gh-pages.
+    # Overrides the top-level `contents: read`: this job creates the tag and the
+    # Release, and pushes the regenerated channel to the ghcup-channel branch.
     permissions:
       contents: write
-    env:
-      TAG: ${{ github.ref_name }}
     steps:
 
     - uses: actions/checkout@v4
@@ -849,12 +926,39 @@ jobs:
       run: |
         set -eux
         ls -l dist/*.tar.xz
-        # ghcup tool version: the tag without the leading 'v'.
-        echo "VERSION=${TAG#v}" >> "$GITHUB_ENV"
+        # The version released, and the ghcup tool version. The build jobs
+        # stamped the compiler with the same string (RELEASE_VERSION), so every
+        # tarball must be named for it; if not, the channel would advertise a
+        # version no bindist provides. See Note [Release versioning] in
+        # plinth-build.sh.
+        VERSION="${REQUESTED_VERSION#v}"
+        for f in dist/*.tar.xz; do
+          case "$(basename "$f")" in
+            "ghc-$VERSION-"*) ;;
+            *) echo "error: $f is not a bindist for version $VERSION"; exit 1 ;;
+          esac
+        done
+        echo "VERSION=$VERSION" >> "$GITHUB_ENV"
+        echo "TAG=v$VERSION" >> "$GITHUB_ENV"
 
     # The install is already validated end-to-end on every platform by the
     # plinth-ghcup-test-* jobs this job `needs`, so no re-validation here.
 
+    # Note [Tagging a release]
+    # ~~~~~~~~~~~~~~~~~~~~~~~~
+    # The tag is created here, at the end, rather than being what starts the
+    # release: everything above has already built and tested this exact commit,
+    # so a v* tag exists only for a revision that passed. A failed or abandoned
+    # release attempt leaves no trace in the tag list, and the checked-out commit
+    # is $GITHUB_SHA -- the revision the run was dispatched on.
+    - name: Tag the release
+      run: |
+        set -eux
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        git tag -a "$TAG" -m "uplc-ghc $VERSION" "$GITHUB_SHA"
+        git push origin "$TAG"
+
     # Publish the Release with all tarballs. Create it if missing, otherwise
     # (re-)upload the assets.
     - name: Create GitHub Release
@@ -871,29 +975,57 @@ jobs:
           gh release upload "$TAG" dist/*.tar.xz --clobber
         fi
 
-    # Regenerate the channel on gh-pages with the real Release download URLs and
-    # push it. The generator merges into the existing versions DB so previously
-    # released versions remain in the channel.
-    - name: Check out gh-pages
-      uses: actions/checkout@v4
-      with:
-        ref: gh-pages
-        path: gh-pages-out
-
-    - name: Regenerate and publish ghcup channel
+    # Regenerate the channel with the real Release download URLs and push it to
+    # the ghcup-channel branch, which is what users point ghcup at. The generator
+    # merges into the existing versions DB so previously released versions remain
+    # in the channel. See Note [ghcup release channel].
+    #
+    # The branch holds nothing but the channel files, so it is built up in a
+    # standalone repo rather than checked out: cloning it into a working tree of
+    # this (very large) repo would mean deleting the whole GHC tree first. It is
+    # created as an orphan on the first release, so no manual setup is needed.
+    - name: Publish the ghcup channel
+      env:
+        GH_TOKEN: ${{ github.token }}
+        CHANNEL_BRANCH: ghcup-channel
+      # no -x: the push URL carries the token (GitHub masks it, but don't print it)
       run: |
-        set -eux
+        set -eu
+        mkdir channel-out
+        (
+          cd channel-out
+          git init -q -b "$CHANNEL_BRANCH"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git remote add origin "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}"
+          if git fetch -q --depth 1 origin "$CHANNEL_BRANCH" 2>/dev/null; then
+            git reset -q --hard FETCH_HEAD
+          else
+            echo "first release: creating the $CHANNEL_BRANCH branch"
+          fi
+        )
         python3 generate-ghcup-metadata.py \
           --version "$VERSION" \
           --base-url "https://github.com/${GITHUB_REPOSITORY}/releases/download/${TAG}" \
-          --db gh-pages-out/ghcup-plinth.versions.json \
-          --output gh-pages-out/ghcup-plinth.yaml \
+          --db channel-out/ghcup-plinth.versions.json \
+          --output channel-out/ghcup-plinth.yaml \
           --release-day "$(date -u +%Y-%m-%d)" \
           --set-latest \
           dist/*.tar.xz
-        cd gh-pages-out
-        git config user.name "github-actions[bot]"
-        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-        git add ghcup-plinth.yaml ghcup-plinth.versions.json
-        git commit -m "ghcup channel: publish plinth ${VERSION} (${TAG})" || echo "no changes to commit"
-        git push
+        cat > channel-out/README.md <<EOF
+        # ghcup channel for the Plinth compiler
+
+        This branch only carries the ghcup metadata for \`uplc-ghc\`; it is not
+        part of the source tree. Both files are generated by CI on a \`v*\` tag
+        (see the \`release\` job in \`.github/workflows/ci.yml\`) -- do not edit
+        them by hand.
+
+            ghcup config add-release-channel https://raw.githubusercontent.com/${GITHUB_REPOSITORY}/${CHANNEL_BRANCH}/ghcup-plinth.yaml
+            ghcup install plinth latest
+        EOF
+        cd channel-out
+        git add -A
+        git commit -q -m "ghcup channel: publish plinth ${VERSION} (${TAG})" \
+          || echo "no changes to commit"
+        git push -q origin "HEAD:$CHANNEL_BRANCH"
+        echo "published https://raw.githubusercontent.com/${GITHUB_REPOSITORY}/${CHANNEL_BRANCH}/ghcup-plinth.yaml"

README.md

@@ -25,7 +25,7 @@ third-party tools); upgrade with `ghcup upgrade` if needed.
 
 Add the release channel once, then install and select a version:
 
-    $ ghcup config add-release-channel https://input-output-hk.github.io/ghc-plinth/ghcup-plinth.yaml
+    $ ghcup config add-release-channel https://raw.githubusercontent.com/input-output-hk/ghc-plinth/ghcup-channel/ghcup-plinth.yaml
     $ ghcup install plinth latest
     $ ghcup set plinth latest          # puts uplc-ghc on PATH
 
@@ -41,7 +41,14 @@ compiler to build a Plinth project:
 published as GitHub Releases for x86_64/aarch64 Linux (glibc and musl), macOS
 (Apple Silicon), and Windows; ghcup picks the right one for your platform.
 
+The channel metadata lives on the [`ghcup-channel`][ghcup-channel] branch of this
+repository and is regenerated by CI on every release. Note that
+`raw.githubusercontent.com` caches for five minutes, so a just-published version
+can take that long to show up.
+
   [ghcup]: https://www.haskell.org/ghcup/ "ghcup"
+  [ghcup-channel]: https://github.com/input-output-hk/ghc-plinth/tree/ghcup-channel
+          "the ghcup-channel branch"
 
 The text below is the upstream GHC README.
 
@@ -75,11 +82,43 @@ The script bootstraps GHC and then builds the Plinth-enabled compiler,
 
  - `REBUILD=1` forces a full rebuild.
  - `RELEASE=1` builds a release flavour including documentation.
+ - `RELEASE_VERSION=9.6.166.1` stamps the compiler with exactly that version
+   instead of the usual `<version>.<date>` snapshot version. Used by CI when
+   building a release; see the next section.
 
 A binary distribution archive (`ghc-<version>-<platform>.tar.xz`) is produced
 under `_build/bindist/`.
 
 
+Making a release
+================
+
+Releases are cut from the Actions tab, not by pushing a tag: go to
+**Actions -> CI -> Run workflow**, pick the branch to release, and fill in
+
+ - `release_version`: the version to release, e.g. `9.6.166.1`;
+ - `publish`: tick it.
+
+`configure.ac` holds the three-component base version (`9.6.166`, bumped
+whenever the `plutus` submodule moves) and `release_version` adds the release
+counter, so `9.6.166.1` produces a compiler reporting exactly `9.6.166.1`. A
+version that does not extend the base, or one that has already been released, is
+rejected within seconds by the `release-precheck` job.
+
+CI then builds every platform and runs the test and ghcup-install suites. Only
+if all of them pass does it tag the revision `v<release_version>`, publish the
+bindists as a GitHub Release, and push the regenerated ghcup channel to the
+`ghcup-channel` branch, where previously released versions are kept and the new
+one becomes `latest`. That branch is created on the first release; nothing needs
+setting up by hand.
+
+Tagging last means a `v*` tag only ever exists for a revision that built and
+passed everywhere: an abandoned or failed release attempt leaves nothing behind
+but a red workflow run. To rehearse one, run the workflow the same way with
+`publish` left off -- identical builds and tests, but nothing is tagged or
+published.
+
+
 How to use it?
 ==============
 

configure.ac

@@ -30,8 +30,11 @@ AC_INIT([The Glorious Glasgow Haskell Compilation System], [9.6.166], [glasgow-h
     # would tell a user which one that is.
     #
     # The fourth component distinguishes builds of the same Plinth version:
-    #  - 9.6.166.DATE for RELEASE=NO (version in this file is [9.6.166])
-    #  - 9.6.166.X for RELEASE=YES, X counting re-releases from 1
+    #  - 9.6.166.DATE for a snapshot build (RELEASE=NO, the default)
+    #  - 9.6.166.X for a released build, X counting releases from 1
+    # Keep the version in this file at three components: plinth-build.sh rewrites
+    # it to the full four-component version and passes RELEASE=YES when building a
+    # release. See Note [Release versioning] there.
     #
     # 166 is numerically below the previous 1501, which encoded a release counter
     # in this component; nothing was ever published as 1501, so no public version