release.yml

name: release

# Tag-triggered release (RELEASE-AND-VERSIONING-STANDARD §4, REL-13/14/15).
# Nothing here trusts the PR's green checkmark on `ci.yml` — every gate is
# re-run at the exact tagged commit. Tag like `v0.1.0` (`git tag -s v0.1.0 -m
# "v0.1.0" && git push origin v0.1.0`).
#
# The release re-verifies at the tag, scans and publishes the container to
# GHCR by digest, builds the sdist+wheel, generates a CycloneDX SBOM, creates
# keyless Sigstore signatures and GitHub build-provenance attestations, creates
# the GitHub Release from the matching CHANGELOG section, then downloads and
# verifies every published artifact (issue #33).

on:
  push:
    tags: ["v*"]

permissions:
  contents: read

# A release publishes GitHub Release assets — never race a second run for the
# same tag (a tag can't be re-pushed, but a manual re-run must queue).
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

jobs:
  # The tag must match the package version (without the leading v) — the
  # single source of version truth is `pyproject.toml` (REL §2).
  version-check:
    name: Validate release metadata
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          persist-credentials: false
      - name: Tag matches pyproject.toml version
        run: |
          tag_version="${GITHUB_REF_NAME#v}"
          pkg_version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
          echo "tag=$tag_version pyproject=$pkg_version"
          if [ "$tag_version" != "$pkg_version" ]; then
            echo "::error::tag $GITHUB_REF_NAME does not match pyproject version $pkg_version"
            exit 1
          fi

      - name: Require a verified signed annotated tag
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          if [ "$(git cat-file -t "refs/tags/${GITHUB_REF_NAME}")" != "tag" ]; then
            echo "::error::${GITHUB_REF_NAME} must be an annotated tag"
            exit 1
          fi
          tag_object="$(git rev-parse "refs/tags/${GITHUB_REF_NAME}")"
          verified="$(gh api "repos/${GITHUB_REPOSITORY}/git/tags/${tag_object}" --jq '.verification.verified')"
          if [ "$verified" != "true" ]; then
            echo "::error::${GITHUB_REF_NAME} is not a cryptographically verified signed tag"
            exit 1
          fi

      - name: CHANGELOG and CITATION match the tag
        run: |
          set -euo pipefail
          version="${GITHUB_REF_NAME#v}"
          citation_version="$(awk '$1 == "version:" {print $2; exit}' CITATION.cff)"
          citation_date="$(awk '$1 == "date-released:" {print $2; exit}' CITATION.cff)"
          tag_date="$(git for-each-ref --format='%(taggerdate:short)' "refs/tags/${GITHUB_REF_NAME}")"
          test "$citation_version" = "$version" || {
            echo "::error::CITATION.cff version ${citation_version} does not match ${version}"; exit 1;
          }
          test "$citation_date" = "$tag_date" || {
            echo "::error::CITATION.cff date-released ${citation_date} does not match tag date ${tag_date}"; exit 1;
          }
          grep -Fq "## [${version}]" CHANGELOG.md || {
            echo "::error::CHANGELOG.md has no ## [${version}] section"; exit 1;
          }

  # Never publish untested code: re-run the exact merge-blocking gate
  # (`make verify` — lint, typecheck, test+coverage, security, a11y, eval) at
  # the tagged commit, not the PR's stale green check. Mirrors ci.yml's
  # toolchain setup exactly so local/CI/release parity holds.
  verify-at-tag:
    name: Verify tagged commit
    needs: [version-check]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          persist-credentials: false

      - name: Set up Python
        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
        with:
          python-version: "3.14"

      # No per-action input disables setup-node's own Node-distribution tool-
      # cache (unlike the opt-in `cache:` package-manager cache, which is left
      # unset below and so never enabled) — zizmor flags any caching action in
      # a tag-triggered workflow at Low confidence; this job only gates the
      # release (it publishes nothing), so a poisoned tool-cache here can't
      # ride into a shipped artifact.
      - name: Set up Node (for the pa11y/axe a11y runner)
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 # zizmor: ignore[cache-poisoning] verify-only job, publishes nothing; no per-action toggle for the Node tool-cache
        with:
          node-version: "20"

      - name: Set up uv (pinned)
        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
        with:
          version: "0.11.26"
          enable-cache: false # release job: no cross-run cache poisoning surface

      - name: Install project (dev + app extras, locked)
        run: |
          uv sync --frozen --extra dev --extra app
          npm install -g pa11y@9.1.1

      - name: Install gitleaks (pinned v8.30.1, checksum-verified)
        run: |
          set -euo pipefail
          curl -sSL -o /tmp/gitleaks.tar.gz \
            https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
          echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb  /tmp/gitleaks.tar.gz" | sha256sum -c -
          tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks
          sudo install -m 0755 /tmp/gitleaks /usr/local/bin/gitleaks
          gitleaks version

      - name: Install osv-scanner (pinned v2.4.0, checksum-verified)
        run: |
          set -euo pipefail
          curl -sSL -o /tmp/osv-scanner \
            https://github.com/google/osv-scanner/releases/download/v2.4.0/osv-scanner_linux_amd64
          echo "15314940c10d26af9c6649f150b8a47c1262e8fc7e17b1d1029b0e479e8ed8a0  /tmp/osv-scanner" | sha256sum -c -
          sudo install -m 0755 /tmp/osv-scanner /usr/local/bin/osv-scanner
          osv-scanner --version

      - name: make verify (re-run every gate at the tagged commit)
        run: make verify

  # Gate the release on the same container CVE scan CI runs on every push to
  # main (container-scan.yml) — a release must not ship a HIGH/CRITICAL image
  # even though the image itself isn't published anywhere by this workflow.
  container-scan-at-tag:
    name: Scan release container
    needs: [version-check]
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          persist-credentials: false
      - name: Build image
        # Static local tag (not the tag ref name itself) — avoids expanding an
        # attacker-influenceable value into a `run:` shell command (zizmor
        # template-injection); matches container-scan.yml's own pattern.
        run: docker build -t queer-the-stacks:scan .
      - name: Scan image for HIGH/CRITICAL CVEs (Trivy)
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          scan-type: image
          image-ref: queer-the-stacks:scan
          vuln-type: os,library
          severity: HIGH,CRITICAL
          ignore-unfixed: true
          exit-code: "1"
          format: table

  build:
    name: Build and attest packages
    needs: [verify-at-tag, container-scan-at-tag]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # keyless OIDC identity for build provenance attestation
      attestations: write # publish the attestation to the repo's attestation store
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          persist-credentials: false
      # No cache in the build/attest path (SLSA build-provenance intent: a
      # cache hit is an unverified input into the artifact we're about to
      # attest and ship — CI-CD-STANDARD cache-poisoning guidance).
      - name: Set up uv (pinned)
        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
        with:
          version: "0.11.26"
          enable-cache: false

      - name: Build sdist + wheel (the ingest/recommender/app packages the image ships)
        run: uv build

      - name: Check metadata
        run: uvx twine check dist/*

      # Supply-chain (SECURITY-AND-SUPPLY-CHAIN-STANDARD §6.2): sync the
      # locked runtime closure and emit a schema-validated CycloneDX 1.7 SBOM
      # for the shipped package.
      - name: Generate CycloneDX SBOM
        run: |
          uv sync --frozen --extra app --no-dev
          uvx --from cyclonedx-bom==7.3.0 cyclonedx-py environment .venv \
            --sv 1.7 --of JSON --pyproject pyproject.toml \
            --output-reproducible --validate -o dist/sbom.cdx.json

      - name: Attest build provenance (keyless OIDC)
        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
        with:
          subject-path: "dist/*"

      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: dist
          path: dist/

  publish-image:
    name: Publish and sign GHCR image
    needs: [verify-at-tag, container-scan-at-tag]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write # publish the release image to GHCR
      id-token: write # obtain the keyless Sigstore identity
      attestations: write # publish image provenance to GitHub
    outputs:
      image: ${{ steps.publish.outputs.image }}
      digest: ${{ steps.publish.outputs.digest }}
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          persist-credentials: false
      - name: Install cosign (pinned)
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
      - name: Build and publish GHCR image by digest
        id: publish
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          image="ghcr.io/${GITHUB_REPOSITORY,,}"
          echo "$GH_TOKEN" | docker login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
          docker build -t "${image}:${GITHUB_REF_NAME}" .
          docker push "${image}:${GITHUB_REF_NAME}"
          digest_ref="$(docker inspect --format='{{index .RepoDigests 0}}' "${image}:${GITHUB_REF_NAME}")"
          test -n "$digest_ref"
          echo "image=$image" >> "$GITHUB_OUTPUT"
          echo "digest=${digest_ref#*@}" >> "$GITHUB_OUTPUT"
      - name: Keyless-sign the image digest
        env:
          IMAGE: ${{ steps.publish.outputs.image }}
          DIGEST: ${{ steps.publish.outputs.digest }}
        run: cosign sign --yes "${IMAGE}@${DIGEST}"
      - name: Attest image build provenance
        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
        with:
          subject-name: ${{ steps.publish.outputs.image }}
          subject-digest: ${{ steps.publish.outputs.digest }}
          push-to-registry: true

  # Create the GitHub Release with the matching CHANGELOG section as notes.
  github-release:
    name: Publish GitHub Release
    needs: [build, publish-image]
    runs-on: ubuntu-latest
    permissions:
      contents: write # create the release and upload its assets
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          persist-credentials: false
      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
        with:
          name: dist
          path: dist/

      - name: Extract CHANGELOG section for this version
        run: |
          version="${GITHUB_REF_NAME#v}"
          awk -v ver="$version" '
            index($0, "## [" ver "]") == 1 { flag = 1; next }
            /^## \[/ { flag = 0 }
            flag' CHANGELOG.md > /tmp/release-notes.md
          if [ -s /tmp/release-notes.md ]; then
            echo "notes extracted for $version:"; cat /tmp/release-notes.md
          else
            echo "::error::no CHANGELOG section found for $version"
            exit 1
          fi

      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          if [ -s /tmp/release-notes.md ]; then
            gh release create "$GITHUB_REF_NAME" dist/* \
              --title "$GITHUB_REF_NAME" --notes-file /tmp/release-notes.md --verify-tag
          fi

  verify-published:
    name: Verify published artifacts
    needs: [build, publish-image, github-release]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read # pull the just-published GHCR image by digest
    steps:
      - name: Set up uv (pinned)
        uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
        with:
          version: "0.11.26"
          enable-cache: false
      - name: Install cosign (pinned)
        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
      - name: Download and validate published release assets
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          mkdir dist
          gh release download "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --dir dist
          test "$(find dist -maxdepth 1 -type f | wc -l)" -ge 3
          uvx twine check dist/*.whl dist/*.tar.gz
          jq -e '.bomFormat == "CycloneDX" and (.components | length > 0)' dist/sbom.cdx.json >/dev/null
          gh attestation verify dist/*.whl dist/*.tar.gz dist/sbom.cdx.json \
            --repo "$GITHUB_REPOSITORY"
      - name: Verify and pull the signed image by digest
        env:
          IMAGE: ${{ needs.publish-image.outputs.image }}
          DIGEST: ${{ needs.publish-image.outputs.digest }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          echo "$GH_TOKEN" | docker login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
          cosign verify \
            --certificate-identity-regexp "^https://github.com/${GITHUB_REPOSITORY}/.github/workflows/release.yml@refs/tags/v" \
            --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
            "${IMAGE}@${DIGEST}"
          docker pull "${IMAGE}@${DIGEST}"