release.yml

name: Release

# Native macOS release workflow.
#
# Current status: MANUAL
#   The exact DMG and Sparkle ZIP assets are produced on the release Mac by
#   scripts/release.sh (Developer ID signing + notarization + stapling) and
#   uploaded together to GitHub Releases. See BUILDING.md.
#   "Building a Release".
#
# Future: automate with a self-hosted macOS runner or GitHub's macos-latest
#   (requires exporting the Developer ID certificate and notary API key as
#   repository secrets).
#
# Windows / Linux: Zerm is a native macOS Swift app (AppKit + SwiftUI).
#   There is no Windows or Linux build. The archived Tauri prototype that
#   previously built cross-platform installers is no longer maintained.

on:
  # Manual trigger only — for running any future automated steps
  workflow_dispatch:
    inputs:
      tag:
        description: "Release tag (for example v2.8.2 or v1.2.8.2)"
        required: true
        type: string

  # Keep the published changelog in step with GitHub Releases.
  #
  # Only `released`. Publishing a release fires `published` AND `released`, and
  # every asset upload fires `edited`, so the old four-type list ran this whole
  # workflow three times per release and raced three identical changelog branches
  # against each other. `deleted` was pointless here: the regenerated changelog
  # reads the releases list, which a deletion also changes, but a deleted release
  # cannot be validated by the tag job below.
  release:
    types: [released]

permissions:
  contents: write
  # createCommitOnBranch needs contents; opening the changelog PR needs this.
  # Without it `gh pr create` fails with "Resource not accessible by integration".
  pull-requests: write

jobs:
  validate-release:
    name: Validate release tag and assets
    runs-on: ubuntu-latest
    env:
      RELEASE_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.event.release.tag_name }}
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          # Tags are not fetched by the default shallow checkout, so `git rev-parse`
          # below reported every tag as missing — including ones that plainly exist.
          fetch-depth: 0

      - name: Verify tag exists
        run: |
          set -euo pipefail
          TAG="$RELEASE_TAG"
          test -n "$TAG" || { echo "::error::Release tag is empty."; exit 1; }
          [[ "$TAG" =~ ^v[0-9]+(\.[0-9]+){2,3}$ ]] || {
            echo "::error::Release tag must be v followed by three or four numeric components: $TAG"
            exit 1
          }
          if git rev-parse --verify "refs/tags/${TAG}^{commit}" >/dev/null 2>&1; then
            echo "Tag $TAG exists — release is valid"
          else
            echo "Tag $TAG not found. Create the tag first:"
            echo "  git tag $TAG && git push origin $TAG"
            exit 1
          fi

      - name: Require exact release assets
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          TAG="$RELEASE_TAG"
          RELEASE_LABEL="${TAG#v}"
          test "$RELEASE_LABEL" != "$TAG" || { echo "::error::Release tag must start with v: $TAG"; exit 1; }
          [[ "$RELEASE_LABEL" =~ ^[0-9]+(\.[0-9]+){2,3}$ ]] || {
            echo "::error::Release tag must contain three or four numeric components: $TAG"
            exit 1
          }

          EXPECTED_DMG="Zerm_${RELEASE_LABEL}_aarch64.dmg"
          EXPECTED_ZIP="Zerm-${RELEASE_LABEL}-macos.zip"
          ASSETS=$(gh release view "$TAG" --json assets --jq '.assets[].name')
          MISSING=0

          for asset in "$EXPECTED_DMG" "$EXPECTED_ZIP"; do
            if printf '%s\n' "$ASSETS" | grep -Fxq "$asset"; then
              echo "Found required asset: $asset"
            else
              echo "::error::Release $TAG is missing exact asset $asset"
              MISSING=1
            fi
          done

          if [ "$MISSING" -ne 0 ]; then
            echo "Upload both exact assets before publishing or validating the release:"
            echo "  gh release upload $TAG $EXPECTED_DMG $EXPECTED_ZIP"
            exit 1
          fi

          {
            echo "RELEASE_LABEL=$RELEASE_LABEL"
            echo "EXPECTED_DMG=$EXPECTED_DMG"
            echo "EXPECTED_ZIP=$EXPECTED_ZIP"
          } >> "$GITHUB_ENV"

      - name: Validate tagged appcast contract
        run: |
          set -euo pipefail
          git show "${RELEASE_TAG}:docs/appcast.xml" > "$RUNNER_TEMP/zerm-appcast.xml"
          git show "${RELEASE_TAG}:Zerm.xcodeproj/project.pbxproj" > "$RUNNER_TEMP/zerm-project.pbxproj"

          python3 - <<'PY'
          import os
          import pathlib
          import re
          import xml.etree.ElementTree as ET

          label = os.environ["RELEASE_LABEL"]
          tag = os.environ["RELEASE_TAG"]
          expected_zip = os.environ["EXPECTED_ZIP"]
          appcast_path = pathlib.Path(os.environ["RUNNER_TEMP"]) / "zerm-appcast.xml"
          project_path = pathlib.Path(os.environ["RUNNER_TEMP"]) / "zerm-project.pbxproj"
          sparkle = "http://www.andymatuschak.org/xml-namespaces/sparkle"

          root = ET.parse(appcast_path).getroot()
          items = root.findall("./channel/item")
          if len(items) != 1:
              raise SystemExit(f"expected exactly one appcast item, found {len(items)}")
          item = items[0]
          title = (item.findtext("title") or "").strip()
          bundle_version = (item.findtext(f"{{{sparkle}}}shortVersionString") or "").strip()
          build_version = (item.findtext(f"{{{sparkle}}}version") or "").strip()
          enclosure = item.find("enclosure")
          if title != label:
              raise SystemExit(f"appcast title {title!r} does not match release label {label!r}")
          if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", bundle_version):
              raise SystemExit(f"appcast bundle version is not Apple Major.Minor.Patch: {bundle_version!r}")
          if not re.fullmatch(r"[1-9][0-9]*", build_version):
              raise SystemExit(f"appcast build version is not a positive integer: {build_version!r}")
          if enclosure is None:
              raise SystemExit("appcast item has no enclosure")
          expected_url = f"https://github.com/arcusis/Zerm/releases/download/{tag}/{expected_zip}"
          if enclosure.get("url") != expected_url:
              raise SystemExit(f"appcast enclosure URL {enclosure.get('url')!r} does not match {expected_url!r}")
          if not enclosure.get(f"{{{sparkle}}}edSignature"):
              raise SystemExit("appcast enclosure has no Sparkle EdDSA signature")

          project = project_path.read_text()
          app_settings = [
              block for block in re.findall(r"buildSettings = \{(.*?)\n\s*\};", project, re.DOTALL)
              if re.search(r"^\s*PRODUCT_BUNDLE_IDENTIFIER = com\.arcusis\.zerm;$", block, re.MULTILINE)
          ]
          if len(app_settings) != 2:
              raise SystemExit(f"expected Debug and Release settings for the Zerm app target, found {len(app_settings)}")
          marketing_versions = {
              match.group(1)
              for block in app_settings
              if (match := re.search(r"^\s*MARKETING_VERSION = ([0-9.]+);$", block, re.MULTILINE))
          }
          build_versions = {
              match.group(1)
              for block in app_settings
              if (match := re.search(r"^\s*CURRENT_PROJECT_VERSION = ([0-9]+);$", block, re.MULTILINE))
          }
          if marketing_versions != {bundle_version}:
              raise SystemExit(f"tagged project marketing versions {marketing_versions} do not match appcast {bundle_version}")
          if build_versions != {build_version}:
              raise SystemExit(f"tagged project build versions {build_versions} do not match appcast {build_version}")

          with open(os.environ["GITHUB_ENV"], "a", encoding="utf-8") as env:
              env.write(f"APPCAST_BUNDLE_VERSION={bundle_version}\n")
              env.write(f"APPCAST_BUILD_VERSION={build_version}\n")
          print(f"Validated {tag}: release label {label}, bundle {bundle_version}, build {build_version}")
          PY

      - name: Validate Sparkle ZIP identity
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          mkdir -p "$RUNNER_TEMP/zerm-release"
          gh release download "$RELEASE_TAG" \
            --pattern "$EXPECTED_ZIP" \
            --dir "$RUNNER_TEMP/zerm-release"

          python3 - <<'PY'
          import os
          import pathlib
          import plistlib
          import zipfile

          archive = pathlib.Path(os.environ["RUNNER_TEMP"]) / "zerm-release" / os.environ["EXPECTED_ZIP"]
          with zipfile.ZipFile(archive) as release_zip:
              plist_entries = [
                  name for name in release_zip.namelist()
                  if name.endswith("Zerm.app/Contents/Info.plist")
              ]
              if len(plist_entries) != 1:
                  raise SystemExit(f"expected one Zerm.app Info.plist, found {len(plist_entries)}")
              info = plistlib.loads(release_zip.read(plist_entries[0]))

          expected = {
              "CFBundleIdentifier": "com.arcusis.zerm",
              "CFBundleShortVersionString": os.environ["APPCAST_BUNDLE_VERSION"],
              "CFBundleVersion": os.environ["APPCAST_BUILD_VERSION"],
          }
          for key, value in expected.items():
              actual = str(info.get(key, ""))
              if actual != value:
                  raise SystemExit(f"ZIP {key} {actual!r} does not match {value!r}")
          print("Sparkle ZIP bundle identity matches the tagged project and appcast")
          PY

  publish-changelog:
    name: Regenerate site changelog
    needs: validate-release
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
        with:
          ref: Production

      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: "22"

      - name: Regenerate derived pages
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: node scripts/build-site.mjs

      # This job cannot publish the changelog itself, and pretending otherwise is
      # what made it useless for so long. The history:
      #
      #   1. It committed as github-actions[bot] and pushed to Production. The
      #      "Require signed commits" ruleset covers ~ALL branches with no bypass
      #      actors, so the push was rejected — every release, silently, which is
      #      how the site changelog got stuck at 2.6.1 while 2.7.0 shipped.
      #   2. Creating the commit via GraphQL createCommitOnBranch fixed the signing
      #      (GitHub signs those server-side) and that part does work.
      #   3. But Production takes changes by pull request only, and the org forbids
      #      GitHub Actions from creating pull requests:
      #        "GitHub Actions is not permitted to create or approve pull requests"
      #      That is an org-wide security policy. Loosening it for a changelog is a
      #      bad trade, so this job no longer tries.
      #
      # Instead it reports drift and fails loudly. Regenerating is a one-liner a
      # maintainer runs with their own credentials, and `make release` does it as
      # part of cutting a release.
      - name: Check the site is in step with published releases
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail

          if git diff --quiet -- docs/; then
            echo "Site is up to date with the published releases."
            exit 0
          fi

          echo "::error::The published site is out of date with the GitHub Releases."
          echo "Stale files:"
          git diff --name-only -- docs/ | sed 's/^/  /'
          echo ""
          echo "Regenerate and open a PR:"
          echo "  node scripts/build-site.mjs && git add docs/ && git commit -m 'Regenerate site changelog from releases'"
          echo ""
          echo "Diff of what would change:"
          git --no-pager diff --stat -- docs/
          exit 1