release.yml

name: Release

on:
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      tag:
        description: SemVer tag to create, rebuild, and publish (for example v1.1.0)
        required: true
        type: string

concurrency:
  group: release-${{ github.event.inputs.tag || github.ref }}
  cancel-in-progress: false

jobs:
  prepare:
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    permissions:
      contents: write
    outputs:
      publish: ${{ steps.target.outputs.publish }}
      tag: ${{ steps.target.outputs.tag }}
      version: ${{ steps.target.outputs.version }}
    steps:
      - name: Validate release automation configuration
        if: github.event_name == 'push'
        shell: bash
        env:
          RELEASE_APP_CLIENT_ID_CONFIGURED: ${{ vars.RELEASE_APP_CLIENT_ID != '' }}
          RELEASE_APP_PRIVATE_KEY_CONFIGURED: ${{ secrets.RELEASE_APP_PRIVATE_KEY != '' }}
        run: |
          set -euo pipefail
          missing=()
          [[ "$RELEASE_APP_CLIENT_ID_CONFIGURED" == "true" ]] || missing+=(RELEASE_APP_CLIENT_ID)
          [[ "$RELEASE_APP_PRIVATE_KEY_CONFIGURED" == "true" ]] || missing+=(RELEASE_APP_PRIVATE_KEY)
          if (( ${#missing[@]} > 0 )); then
            {
              echo "## Release automation is not configured"
              echo
              echo "Missing repository configuration: \`${missing[*]}\`."
              echo "Follow \`docs/RELEASING.md\` to install the least-privilege GitHub App, then rerun this workflow."
            } >> "$GITHUB_STEP_SUMMARY"
            printf 'Missing release automation configuration: %s\n' "${missing[*]}" >&2
            echo "See docs/RELEASING.md for the required GitHub App setup." >&2
            exit 1
          fi

      - name: Create short-lived release automation token
        if: github.event_name == 'push'
        id: app-token
        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
        with:
          client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
          private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
          owner: ${{ github.repository_owner }}
          repositories: ${{ github.event.repository.name }}
          permission-contents: write
          permission-issues: write
          permission-pull-requests: write

      - name: Create or update the release pull request
        if: github.event_name == 'push'
        id: release
        uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
        with:
          token: ${{ steps.app-token.outputs.token }}
          config-file: release-please-config.json
          manifest-file: .release-please-manifest.json

      - name: Resolve release target
        id: target
        shell: bash
        env:
          EVENT_NAME: ${{ github.event_name }}
          MANUAL_TAG: ${{ inputs.tag }}
          RELEASE_CREATED: ${{ steps.release.outputs.release_created }}
          RELEASE_TAG: ${{ steps.release.outputs.tag_name }}
          GH_TOKEN: ${{ github.token }}
        run: |
          set -euo pipefail
          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
            if [[ ! "$MANUAL_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
              echo "The tag must be a stable SemVer tag beginning with v." >&2
              exit 1
            fi
            if gh release view "$MANUAL_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
              is_draft=$(gh release view "$MANUAL_TAG" --repo "$GITHUB_REPOSITORY" --json isDraft --jq .isDraft)
              if [[ "$is_draft" != "true" ]]; then
                echo "Published releases are immutable; create a new version instead." >&2
                exit 1
              fi
            else
              if ! gh api "repos/$GITHUB_REPOSITORY/git/ref/tags/$MANUAL_TAG" >/dev/null 2>&1; then
                gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" \
                  -f "ref=refs/tags/$MANUAL_TAG" \
                  -f "sha=$GITHUB_SHA" >/dev/null
              fi
              gh release create "$MANUAL_TAG" \
                --repo "$GITHUB_REPOSITORY" \
                --title "$MANUAL_TAG" \
                --generate-notes \
                --verify-tag \
                --draft
            fi
            tag="$MANUAL_TAG"
            publish=true
          elif [[ "$RELEASE_CREATED" == "true" ]]; then
            tag="$RELEASE_TAG"
            publish=true
          else
            tag=""
            publish=false
          fi
          echo "publish=$publish" >> "$GITHUB_OUTPUT"
          echo "tag=$tag" >> "$GITHUB_OUTPUT"
          echo "version=${tag#v}" >> "$GITHUB_OUTPUT"

  python-artifacts:
    needs: prepare
    if: needs.prepare.outputs.publish == 'true'
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    permissions:
      contents: read
      id-token: write
      attestations: write
      artifact-metadata: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.prepare.outputs.tag }}
      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: "3.13"
      - run: python -m pip install "uv==0.11.24"
      - run: uv sync --frozen --extra dev --extra s3
      - run: uv run ruff check .
      - run: uv run mypy src
      - run: uv run pytest --cov=github_backup --cov-report=term-missing --cov-fail-under=80
      - run: uv run pip-audit
      - run: uv build --out-dir dist

      - name: Verify package version and installation
        env:
          EXPECTED_VERSION: ${{ needs.prepare.outputs.version }}
        run: |
          set -euo pipefail
          package_version=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
          test "$package_version" = "$EXPECTED_VERSION"
          python -m venv /tmp/github-backup-release-test
          /tmp/github-backup-release-test/bin/python -m pip install --no-deps dist/*.whl
          test "$(/tmp/github-backup-release-test/bin/github-backup --version)" = "github-backup $EXPECTED_VERSION"
          /tmp/github-backup-release-test/bin/github-backup help run >/dev/null

      - name: Generate SPDX SBOM
        uses: anchore/sbom-action@66cbf4bc1f1c0d2edc94016e65bc221b6bb0ad6c # v0.24.3
        with:
          file: dist/github_backup-${{ needs.prepare.outputs.version }}-py3-none-any.whl
          format: spdx-json
          output-file: dist/github-backup-${{ needs.prepare.outputs.version }}.spdx.json
          upload-artifact: false
          upload-release-assets: false

      - name: Create SHA-256 checksums
        run: |
          set -euo pipefail
          cd dist
          find . -maxdepth 1 -type f ! -name SHA256SUMS -print0 \
            | sort -z \
            | xargs -0 sha256sum \
            | sed 's#  \./#  #' > SHA256SUMS
          sha256sum --check SHA256SUMS

      - name: Attest build provenance
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-path: |
            dist/*.whl
            dist/*.tar.gz
            dist/*.spdx.json

      - name: Attest SBOM
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-path: dist/*.whl
          sbom-path: dist/github-backup-${{ needs.prepare.outputs.version }}.spdx.json

      - name: Preserve release files
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: release-files-${{ needs.prepare.outputs.tag }}
          path: dist/
          if-no-files-found: error
          retention-days: 14

  container:
    needs: prepare
    if: needs.prepare.outputs.publish == 'true'
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    permissions:
      contents: read
      packages: write
      id-token: write
      attestations: write
      artifact-metadata: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ needs.prepare.outputs.tag }}
      - name: Build local image for vulnerability gate
        run: docker build --pull --provenance=false --tag github-backup:release-scan .
      - name: Scan container for actionable high/critical vulnerabilities
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          image-ref: github-backup:release-scan
          scanners: vuln
          vuln-type: os,library
          severity: CRITICAL,HIGH
          ignore-unfixed: true
          exit-code: "1"
      - name: Resolve image name
        id: image
        shell: bash
        run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
      - uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ github.token }}
      - name: Generate container metadata
        id: metadata
        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        with:
          images: ${{ steps.image.outputs.name }}
          tags: |
            type=semver,pattern={{version}},value=${{ needs.prepare.outputs.tag }}
            type=semver,pattern={{major}}.{{minor}},value=${{ needs.prepare.outputs.tag }}
            type=semver,pattern={{major}},value=${{ needs.prepare.outputs.tag }}
            type=raw,value=latest
          labels: |
            org.opencontainers.image.description=Production backups for GitHub repositories, gists, and optional service data
            org.opencontainers.image.licenses=GPL-3.0-only
      - name: Build and publish multi-architecture image
        id: build
        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.metadata.outputs.tags }}
          labels: ${{ steps.metadata.outputs.labels }}
          sbom: true
          provenance: mode=max
          cache-from: type=gha
          cache-to: type=gha,mode=max
      - name: Attest container provenance
        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-name: ${{ steps.image.outputs.name }}
          subject-digest: ${{ steps.build.outputs.digest }}
          push-to-registry: true

  finalize:
    needs: [prepare, python-artifacts, container]
    if: >-
      always() &&
      needs.prepare.outputs.publish == 'true' &&
      needs.python-artifacts.result == 'success' &&
      needs.container.result == 'success'
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    permissions:
      contents: write
    steps:
      - name: Download release files
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release-files-${{ needs.prepare.outputs.tag }}
          path: release-files
      - name: Upload assets and publish release
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ needs.prepare.outputs.tag }}
        run: |
          set -euo pipefail
          gh release upload "$RELEASE_TAG" release-files/* --clobber --repo "$GITHUB_REPOSITORY"
          gh release edit "$RELEASE_TAG" --draft=false --latest --repo "$GITHUB_REPOSITORY"