release.yml

name: Release

# Publishes a pushed v* tag; nothing else triggers this, and ci.yml never fires for tags.
on:
  push:
    tags:
      - 'v*'

# No concurrency block: cancelling mid-upload would leave a partial release.
# Keep the tag-only trigger: build-armv6.yml's cancel-in-progress is safe only because this run is on a tag ref.

permissions:
  contents: read

defaults:
  run:
    shell: bash

jobs:
  # Seconds-cheap checks on the tag before any runner builds; the later asset assertion is authoritative.
  preflight:
    name: preflight
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    outputs:
      version: ${{ steps.version.outputs.version }}
      notes: ${{ steps.notes.outputs.notes }}
    steps:
      - name: Check out
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

      - name: Check the tag names the version this source reports
        id: version
        env:
          TAG: ${{ github.ref_name }}
        run: |
          # Prereleases (v0.2.0-rc1) are refused rather than published as latest.
          [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || {
            echo "::error::tag $TAG is not vMAJOR.MINOR.PATCH; this workflow publishes releases only"
            exit 1
          }

          # project(VERSION) must match the tag; counted to catch a duplicate. `|| true`: grep -c exits 1 on 0 under -e.
          pattern='^[[:space:]]*VERSION [0-9]+\.[0-9]+\.[0-9]+$'
          matches="$(grep -cE "$pattern" CMakeLists.txt || true)"
          [ "$matches" = 1 ] || {
            echo "::error::expected exactly one VERSION line in CMakeLists.txt, found $matches"
            exit 1
          }
          version="$(grep -E "$pattern" CMakeLists.txt | awk '{print $2}')"

          echo "tag $TAG, CMakeLists.txt VERSION $version"
          [ "$TAG" = "v$version" ] || {
            echo "::error::tag $TAG does not match CMakeLists.txt VERSION $version -- bump one to match the other"
            exit 1
          }
          echo "version=$version" >>"$GITHUB_OUTPUT"

      # docs/release-notes/<version>.md must exist; the release job has no checkout, so it is read here.
      - name: Check the tag carries the release notes it will publish
        id: notes
        env:
          TAG: ${{ github.ref_name }}
          VERSION: ${{ steps.version.outputs.version }}
        run: |
          notes="docs/release-notes/$VERSION.md"
          [ -f "$notes" ] || {
            echo "::error::$notes does not exist; add it and re-cut $TAG"
            exit 1
          }
          # Not [ -s ], which passes a file holding only a newline.
          grep -q '[^[:space:]]' "$notes" || {
            echo "::error::$notes has no content; write it and re-cut $TAG"
            exit 1
          }

          # Unpaired fences would break the fence-aware scan below. `|| true`, as above.
          fences="$(grep -c '^```' "$notes" || true)"
          [ $((fences % 2)) -eq 0 ] || {
            echo "::error::$notes leaves a \`\`\` fence open -- $fences fence lines, an odd count; close it at column 0 and re-cut $TAG"
            exit 1
          }

          # `#`/`##` headings outrank the release title; fence-aware so shell comments in code blocks pass.
          banners="$(awk '/^```/ { fence = !fence; next }
                          !fence && /^##? / { printf "%d: %s\n", NR, $0 }' "$notes")"
          [ -z "$banners" ] || {
            echo "$banners"
            echo "::error::those lines in $notes are ## or shallower; start the sections at ### and re-cut $TAG"
            exit 1
          }

          # A job output, not an artifact, so dist/ stays exactly the published set. Random heredoc delimiter.
          delimiter="NOTES_$(od -An -N16 -tx1 /dev/urandom | tr -d ' \n')"
          {
            echo "notes<<$delimiter"
            cat "$notes"
            echo
            echo "$delimiter"
          } >>"$GITHUB_OUTPUT"

          echo "--- $notes ---"
          cat "$notes"

      # gh release create happily adds a second release to a tag, so refuse one already published.
      - name: Refuse a tag that already carries a release
        env:
          TAG: ${{ github.ref_name }}
          GH_REPO: ${{ github.repository }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # Listed, not `releases/tags/$TAG`, whose miss and error look alike and fail open.
          existing="$(gh api "repos/$GH_REPO/releases" --paginate \
            --jq '.[] | select(.tag_name == env.TAG) | "  \(.html_url)  draft=\(.draft)  assets=\(.assets | length)"')"
          [ -z "$existing" ] || {
            echo "$existing"
            echo "::error::$TAG already has a release; delete it before re-cutting this tag"
            exit 1
          }
          echo "no release claims $TAG yet"

  # The five build.yml legs, after preflight.
  build:
    needs: preflight
    uses: ./.github/workflows/build.yml

  # linux-armv6, blocking: a red ARMv6 build fails the release.
  build-armv6:
    needs: preflight
    uses: ./.github/workflows/build-armv6.yml

  release:
    name: release
    needs: [preflight, build, build-armv6]
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    # The only write scope on this repository.
    permissions:
      contents: write
    env:
      TAG: ${{ github.ref_name }}
      VERSION: ${{ needs.preflight.outputs.version }}
      # gh's target, instead of a checkout.
      GH_REPO: ${{ github.repository }}
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      # merge-multiple, and no name or pattern: the assertion below judges the full set.
      - name: Download what the builds produced
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
        with:
          path: dist
          merge-multiple: true

      # Diff the downloaded set against the expected assets: a green build may have uploaded nothing.
      - name: Assert the release is complete before creating anything
        run: |
          # File names, spelled out; macOS contributes a tarball and a .pkg.
          expected=$(mktemp)
          {
            for leg in linux-x86_64 linux-arm64 linux-armv7 linux-armv6 macos-arm64; do
              echo "sendspin-cli-$VERSION-$leg.tar.gz"
            done
            echo "sendspin-cli-$VERSION-macos-arm64.pkg"
          } | sort >"$expected"

          actual=$(mktemp)
          (cd dist && find . ! -type d | sed 's|^\./||') | sort >"$actual"

          echo 'What the build handed over:'
          cat "$actual"
          diff -u "$expected" "$actual" || {
            echo "::error::what was downloaded is not the set $TAG is supposed to publish"
            exit 1
          }

      # Run in dist/ so SHA256SUMS holds bare filenames.
      - name: Checksum what is being published
        run: |
          cd dist
          # The .pkg is checksummed too; an unmatched glob errors under -e, and the set is already asserted.
          sha256sum -- *.tar.gz *.pkg >SHA256SUMS
          cat SHA256SUMS

      - name: Write the release notes
        env:
          # Passed via env, never interpolated, so notes text is never parsed as expression or shell.
          NOTES: ${{ needs.preflight.outputs.notes }}
        run: |
          # A missing output expands to empty; refuse rather than publish only the tail.
          [ -n "$NOTES" ] || {
            echo "::error::the notes preflight read did not reach this job; refusing to publish $TAG with a body it did not write"
            exit 1
          }

          # Notes first, verbatim, then a blank line before the fixed tail.
          printf '%s\n\n' "$NOTES" >notes.md

          # Quoted heredoc: backticks and $ belong to the reader. Only what is true of every release.
          cat >>notes.md <<'NOTES'
          ### What this build is

          sendspin-cli @VERSION@. The version of the sendspin-cpp library it is linked against
          is pinned at build time and printed on the second line of `sendspin-cli --version`,
          alongside this one on the first.

          Installing, verifying `SHA256SUMS` and the macOS Gatekeeper situation are in the
          [wiki](https://github.com/@REPO@/wiki) — [Installation](https://github.com/@REPO@/wiki/Installation),
          or [Getting Started on a Raspberry Pi](https://github.com/@REPO@/wiki/Getting-Started-on-a-Raspberry-Pi)
          for the two 32-bit ARM archives. Each archive also carries its own `BUILD-INFO.txt`,
          with the install command already filled in for its platform.

          The macOS binary and the `.pkg` around it are **unsigned** — ad-hoc signed, which is
          the minimum an arm64 Mach-O needs to execute at all, and carries no developer identity
          — so Gatekeeper refuses them until you say otherwise. Said here rather than only behind
          a link because it is worth knowing before you download; what to do about it is under
          [the macOS installation guide](https://github.com/@REPO@/wiki/Installation#macos).

          - [README](https://github.com/@REPO@/blob/@TAG@/README.md) — what it is, how to run
            it, and how to contribute
          - [Contributors](https://github.com/@REPO@/blob/@TAG@/contributors.md) — development,
            testing, CI, and release guidance
          - [Roadmap](https://github.com/@REPO@/blob/@TAG@/docs/ROADMAP.md) — what shipped and
            what is owed, item by item
          NOTES

          # One substitution pass, so nothing in the body is ever shell-expanded. Links pin to the tag.
          sed -i -e "s|@VERSION@|$VERSION|g" -e "s|@REPO@|$GH_REPO|g" -e "s|@TAG@|$TAG|g" notes.md
          echo '--- notes.md ---'
          cat notes.md

      # Draft, then publish only after asset checks, tracked by release id since a tag can name several drafts.
      # --verify-tag stops gh creating a missing tag. Re-run failed jobs only: artifact names cannot repeat.
      - name: Create the release as a draft
        id: draft
        run: |
          # gh is the one unpinned tool, so log its version.
          gh --version
          echo "Publishing $TAG (version $VERSION) with:"
          ls -l dist

          # stdout is the release URL.
          gh release create "$TAG" \
            --verify-tag \
            --title "sendspin-cli $VERSION" \
            --notes-file notes.md \
            --draft \
            dist/*.tar.gz dist/*.pkg dist/SHA256SUMS | tee created.txt

          # Resolve the draft's numeric id from its html_url once; later steps use the REST id endpoints.
          url="$(tail -n1 created.txt)"
          release_id="$(RELEASE_URL="$url" gh api "repos/$GH_REPO/releases" --paginate \
            --jq '.[] | select(.html_url == env.RELEASE_URL) | .id')"
          case "$release_id" in
            ''|*[!0-9]*)
              echo "::error::could not resolve a single release id for $url; got: $release_id"
              exit 1
              ;;
          esac

          echo "draft $url is release id $release_id"
          echo "release_id=$release_id" >>"$GITHUB_OUTPUT"

      - name: Assert every asset arrived, then publish
        env:
          RELEASE_ID: ${{ steps.draft.outputs.release_id }}
        run: |
          expected=$(mktemp)
          {
            echo SHA256SUMS
            for leg in linux-x86_64 linux-arm64 linux-armv7 linux-armv6 macos-arm64; do
              echo "sendspin-cli-$VERSION-$leg.tar.gz"
            done
            echo "sendspin-cli-$VERSION-macos-arm64.pkg"
          } | sort >"$expected"

          # Read back by id: releases/tags/<tag> never returns drafts, which once failed every release.
          actual=$(mktemp)
          gh api "repos/$GH_REPO/releases/$RELEASE_ID" --jq '.assets[].name' | sort >"$actual"

          echo 'What the draft release holds:'
          cat "$actual"
          diff -u "$expected" "$actual" || {
            echo "::error::draft release $RELEASE_ID for $TAG is missing assets and will not be published; delete it and re-run the failed jobs"
            exit 1
          }

          # -F, not -f: -f sends the string "false", leaving a draft.
          gh api -X PATCH "repos/$GH_REPO/releases/$RELEASE_ID" -F draft=false --silent
          echo "Published: $(gh api "repos/$GH_REPO/releases/$RELEASE_ID" --jq .html_url)"