release.yml

name: Release

# Task 36: tag-driven release pipeline.
#
#   version-check   tag == cmake/Version.cmake (+ api-diff three-source check
#                   and frozen API surface)
#   sdk-package     Linux x86_64 SDK tarball: 8 static libs + headers +
#                   lib/cmake/fulla-*/{Config,ConfigVersion,Targets}.cmake
#                   via `cmake --install`; validated by configuring + building
#                   examples/full-stack-host against the INSTALLED prefix
#   images          backend / frontend / admin images, amd64 + arm64, each on
#                   a NATIVE runner (no QEMU; the C++ build is too slow under
#                   emulation), pushed to GHCR as <version>-<arch>
#   manifest        multi-arch manifests <version> + latest via imagetools;
#                   then (Task 38) cosign keyless signatures on the manifest
#                   digests + per-image SPDX SBOMs via syft
#   github-release  GitHub Release: notes generated by git-cliff (cliff.toml,
#                   conventional commits), SDK tarball + all SBOMs attached;
#                   also pushes the nested clients/go/v<version> tag the Go
#                   module proxy needs for the subdirectory module
#   sdk-python      clients/python package: version-linkage check + sdist/
#                   wheel build (always) + PyPI publish (tag only, and only
#                   once the PYPI_API_TOKEN secret is configured)
#
# Trigger: strict SemVer tags only (v1.2.3). Suffixed tags such as
# v1.0.0-skills-modernization intentionally do NOT release.
# workflow_dispatch runs everything as a DRY RUN: images are built but not
# pushed; manifest + release are skipped.

on:
  push:
    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
  workflow_dispatch:

permissions:
  contents: write # create the GitHub Release
  packages: write # push images to GHCR
  id-token: write # cosign keyless signing (OIDC identity, Task 38)

concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false # never cancel a half-pushed release

env:
  # GHCR namespace; repository_owner is already lowercase (GHCR requirement).
  IMAGE_PREFIX: ghcr.io/${{ github.repository_owner }}/fulla

jobs:
  version-check:
    name: Version & API Surface Check
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    outputs:
      version: ${{ steps.ver.outputs.version }}
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0

      - name: Read version from cmake/Version.cmake
        id: ver
        run: |
          major=$(grep -oP 'FULLA_PROJECT_VERSION_MAJOR \K\d+' cmake/Version.cmake)
          minor=$(grep -oP 'FULLA_PROJECT_VERSION_MINOR \K\d+' cmake/Version.cmake)
          patch=$(grep -oP 'FULLA_PROJECT_VERSION_PATCH \K\d+' cmake/Version.cmake)
          echo "version=${major}.${minor}.${patch}" >> "$GITHUB_OUTPUT"

      - name: Tag must match the repo version
        if: github.ref_type == 'tag'
        run: |
          tag_version="${GITHUB_REF_NAME#v}"
          repo_version="${{ steps.ver.outputs.version }}"
          if [ "$tag_version" != "$repo_version" ]; then
            echo "::error::tag $GITHUB_REF_NAME != cmake/Version.cmake $repo_version"
            exit 1
          fi

      - name: OpenAPI spec governance check (version sync + 3-layer consistency)
        # Spec-governance M0 backstop: the published spec must carry the
        # released version. Uses the PyYAML-optional gate script (no hard
        # dependency on runner-image Python packages) and re-validates the
        # full routes/docs/yaml consistency on the release ref.
        run: python3 tools/openapi-governance/check_spec_governance.py

      - name: API surface frozen at this version (api-diff)
        # Also cross-checks cmake/Version.cmake vs CMakeLists.txt vs conanfile.py.
        run: python3 tools/api-diff/api_diff.py

  sdk-package:
    name: SDK Package (linux-x86_64)
    needs: version-check
    runs-on: ubuntu-24.04
    timeout-minutes: 90
    env:
      VERSION: ${{ needs.version-check.outputs.version }}
      PRESET_DIR: build/linux-release
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0

      - name: Install Linux build dependencies
        # Same rationale as _build-test.yml: library deps come from Conan;
        # uuid-dev because Drogon's recipe does not wrap libuuid on Linux.
        run: |
          sudo apt-get update
          sudo apt-get install -y git gcc g++ cmake uuid-dev

      - name: Install Conan
        run: |
          pip install conan
          conan profile detect --force

      - name: Cache Conan packages
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.conan2
          # runner.arch added vs ci.yml key: keeps this reusable if an arm64
          # SDK job is ever added (runner.os alone is "Linux" on both).
          key: conan-${{ runner.os }}-${{ runner.arch }}-v1-cpp17-${{ hashFiles('conanfile.py', 'conan.lock') }}
          restore-keys: |
            conan-${{ runner.os }}-${{ runner.arch }}-v1-cpp17-

      - name: Configure CMake using Conan
        run: |
          rm -rf "$PRESET_DIR"
          conan install . --output-folder="$PRESET_DIR" --build=missing -s build_type=Release -s compiler.cppstd=17

      - name: Add drogon_ctl (Conan package) to PATH
        # drogon_create_views() invokes `drogon_ctl` at BUILD time (needed by
        # both the product build and the full-stack-host consumption smoke).
        run: |
          data_file=$(find "$PRESET_DIR" -maxdepth 1 -name 'Drogon-*-data.cmake' | head -n1)
          if [ -z "$data_file" ]; then
            echo "::error::Could not find Drogon-*-data.cmake under $PRESET_DIR/"
            exit 1
          fi
          drogon_folder=$(grep -E 'set\(drogon_PACKAGE_FOLDER_RELEASE "' "$data_file" | sed -E 's/.*"(.+)".*/\1/')
          if [ -z "$drogon_folder" ] || [ ! -x "$drogon_folder/bin/drogon_ctl" ]; then
            echo "::error::drogon_ctl not found under $drogon_folder/bin"
            exit 1
          fi
          echo "$drogon_folder/bin" >> "$GITHUB_PATH"

      - name: Configure and build
        run: |
          cmake --preset linux-release
          cmake --build --preset linux-release

      - name: Install SDK to staging prefix
        # Install rules live in the libs/ layer only (fulla_package()):
        # 8 static libs + headers + lib/cmake configs. The server binary is
        # deliberately NOT installed -- it ships via the images below.
        run: |
          cmake --install "$PRESET_DIR" --prefix "stage/fulla-sdk-${VERSION}-linux-x86_64"

      - name: Consumption smoke against the INSTALLED prefix
        # examples/full-stack-host is a standalone find_package(fulla-drogon)
        # consumer; CI's SdkSmoke gate exercises it against the build tree --
        # here we point it at the install tree, proving the tarball content is
        # consumable exactly as docs/sdk/sdk-integration-guide.md describes.
        run: |
          cmake -S examples/full-stack-host -B build/sdk-install-smoke \
            -DCMAKE_BUILD_TYPE=Release \
            -DCMAKE_TOOLCHAIN_FILE="$PWD/$PRESET_DIR/conan_toolchain.cmake" \
            -DCMAKE_PREFIX_PATH="$PWD/stage/fulla-sdk-${VERSION}-linux-x86_64"
          cmake --build build/sdk-install-smoke -j"$(nproc)"

      - name: Create tarball
        run: |
          tar -C stage -czf "fulla-sdk-${VERSION}-linux-x86_64.tar.gz" \
            "fulla-sdk-${VERSION}-linux-x86_64"
          sha256sum "fulla-sdk-${VERSION}-linux-x86_64.tar.gz" \
            > "fulla-sdk-${VERSION}-linux-x86_64.tar.gz.sha256"

      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: sdk-linux-x86_64
          path: |
            fulla-sdk-*.tar.gz
            fulla-sdk-*.tar.gz.sha256
          if-no-files-found: error

  images:
    name: Images (${{ matrix.arch }})
    needs: version-check
    strategy:
      fail-fast: false
      matrix:
        include:
          - arch: amd64
            runner: ubuntu-24.04
          - arch: arm64
            runner: ubuntu-24.04-arm # native build; C++ under QEMU is impractical
    runs-on: ${{ matrix.runner }}
    timeout-minutes: 150 # backend compiles Drogon + all Conan deps from source
    env:
      VERSION: ${{ needs.version-check.outputs.version }}
      ARCH: ${{ matrix.arch }}
      # Dry run (workflow_dispatch): build everything, push nothing.
      PUSH: ${{ github.ref_type == 'tag' }}
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0

      - uses: docker/setup-buildx-action@f7ce87c1d6bead3e36075b2ce75da1f6cc28aaca # v3.9.0

      - name: Log in to GHCR
        if: env.PUSH == 'true'
        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build backend image
        # Same context/target as deploy/docker/docker-compose.yml fulla-backend.
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          file: deploy/docker/Dockerfile
          target: backend-runtime
          push: ${{ env.PUSH == 'true' }}
          tags: ${{ env.IMAGE_PREFIX }}-backend:${{ env.VERSION }}-${{ env.ARCH }}

      - name: Build frontend image
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          file: deploy/docker/Dockerfile
          target: frontend-runtime
          push: ${{ env.PUSH == 'true' }}
          tags: ${{ env.IMAGE_PREFIX }}-frontend:${{ env.VERSION }}-${{ env.ARCH }}

      - name: Build admin image
        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: frontends/admin
          file: frontends/admin/Dockerfile
          push: ${{ env.PUSH == 'true' }}
          tags: ${{ env.IMAGE_PREFIX }}-admin:${{ env.VERSION }}-${{ env.ARCH }}

  manifest:
    name: Multi-Arch Manifests
    needs: [version-check, images]
    if: github.ref_type == 'tag'
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    env:
      VERSION: ${{ needs.version-check.outputs.version }}
    steps:
      - name: Log in to GHCR
        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Merge per-arch tags into <version> + latest
        run: |
          for image in backend frontend admin; do
            ref="${IMAGE_PREFIX}-${image}"
            docker buildx imagetools create \
              -t "${ref}:${VERSION}" -t "${ref}:latest" \
              "${ref}:${VERSION}-amd64" "${ref}:${VERSION}-arm64"
            docker buildx imagetools inspect "${ref}:${VERSION}"
          done

      # ---- Task 38: supply-chain artifacts -------------------------------
      - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2

      - name: Sign multi-arch manifests (cosign keyless, OIDC)
        # Sign by digest, not tag -- tags are mutable. Verify with:
        #   cosign verify ghcr.io/<owner>/fulla-backend:<version> \
        #     --certificate-identity-regexp 'github.com/<owner>/.+/.github/workflows/release.yml' \
        #     --certificate-oidc-issuer https://token.actions.githubusercontent.com
        run: |
          for image in backend frontend admin; do
            ref="${IMAGE_PREFIX}-${image}"
            digest=$(docker buildx imagetools inspect "${ref}:${VERSION}" \
              --format '{{json .Manifest}}' | jq -r .digest)
            cosign sign --yes "${ref}@${digest}"
          done

      - name: Install syft
        uses: anchore/sbom-action/download-syft@3ad7283483fc7af8ff2b4ea19663c2d5ca935e26 # v0.24.2
        with:
          syft-version: v1.19.0

      - name: Generate image SBOMs (SPDX JSON)
        # One SBOM per image from the pushed multi-arch manifest (linux/amd64
        # platform slice; both arches are built from identical inputs).
        run: |
          for image in backend frontend admin; do
            syft "registry:${IMAGE_PREFIX}-${image}:${VERSION}" \
              --platform linux/amd64 -o spdx-json \
              > "fulla-${image}-${VERSION}.spdx.json"
          done

      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: image-sboms
          path: "*.spdx.json"
          if-no-files-found: error

  github-release:
    name: GitHub Release
    needs: [version-check, sdk-package, manifest]
    if: github.ref_type == 'tag'
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    env:
      GH_TOKEN: ${{ github.token }}
      VERSION: ${{ needs.version-check.outputs.version }}
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
        with:
          fetch-depth: 0 # git-cliff needs full history + tags for the notes

      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: sdk-linux-x86_64

      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: image-sboms

      - name: Install syft
        uses: anchore/sbom-action/download-syft@3ad7283483fc7af8ff2b4ea19663c2d5ca935e26 # v0.24.2
        with:
          syft-version: v1.19.0

      - name: Generate source SBOM (SPDX JSON)
        # Catalogues the repo's declared dependency surface: conan.lock (C++)
        # plus the two frontend package-lock.json files.
        run: |
          syft "dir:." --exclude ./build --exclude ./stage -o spdx-json \
            > "fulla-source-${VERSION}.spdx.json"

      - name: Generate release notes (git-cliff)
        uses: orhun/git-cliff-action@3d96a18cc4ec17e9dc69ddcc424ccafaf1f78ce2 # v4.9.0
        with:
          config: cliff.toml
          args: --latest --strip header
        env:
          OUTPUT: RELEASE_NOTES.md

      - name: Guard notes size (fallback to curated CHANGELOG section)
        # git-cliff --latest diffs against the previous tag; when none exists
        # (the v1.0.0 series reset deleted the old series) it spans the whole
        # history and blows past GitHub's 125k-char release-body limit (422).
        run: |
          if [ ! -s RELEASE_NOTES.md ] || [ "$(wc -c < RELEASE_NOTES.md)" -gt 120000 ]; then
            echo "::warning::cliff notes empty/oversized; falling back to CHANGELOG section"
            awk -v ver="${GITHUB_REF_NAME#v}" '
              BEGIN { p = 0 }
              /^## \[/ { p = (index($0, "[" ver "]") == 4) ? 1 : 0 }
              p { print }
            ' CHANGELOG.md > RELEASE_NOTES.md
          fi
          # Hard stop rather than a 422 downstream if even the fallback failed.
          test -s RELEASE_NOTES.md || { echo "::error::empty release notes"; exit 1; }
          echo "notes size: $(wc -c < RELEASE_NOTES.md) bytes"

      - name: Splice curated breaking-change entries into the notes
        # git-cliff rebuilds notes from conventional commits and cannot carry
        # the curated migration guidance in CHANGELOG.md. The versioning
        # policy requires the "⚠️ Breaking (...)" entries (any category:
        # security hardening, client identity, environment variables, ...)
        # in release notes, so
        # extract every such bullet from the released CHANGELOG section and
        # insert it right under the version heading. A bullet may wrap over
        # several lines; the capture ends at the next bullet or heading.
        run: |
          ver="${GITHUB_REF_NAME#v}"
          # Capture styles (v1.4.0 lesson: the bullet-marker-only match missed
          # a section whose Breaking markers live in the HEADING):
          #   1. heading-driven — any "### ⚠? Breaking ..." section: every
          #      bullet under it is captured until the next heading;
          #   2. legacy inline marker — a bullet itself containing
          #      "Breaking (" starts a capture that ends at the next bullet.
          awk -v ver="$ver" '
            BEGIN { p = 0; inb = 0; hdr = 0 }
            /^## \[/ { p = (index($0, "[" ver "]") == 4) ? 1 : 0; inb = 0 }
            p && /^### / { inb = ($0 ~ /Breaking/) ? 1 : 0 }
            p && /^- /  { if (inb == 0 && $0 ~ /Breaking \(/) inb = 1 }
            p && inb {
              if (!hdr) { print ""; print "### ⚠️ Breaking / Required reading before upgrading"; print ""; hdr = 1 }
              print
            }
          ' CHANGELOG.md > BREAKING.md
          if [ -s BREAKING.md ]; then
            awk 'NR==1 { print; while ((getline l < "BREAKING.md") > 0) print l; close("BREAKING.md"); next } { print }' \
              RELEASE_NOTES.md > RELEASE_NOTES.tmp && mv RELEASE_NOTES.tmp RELEASE_NOTES.md
            echo "spliced $(grep -c '^- ' BREAKING.md) breaking entries into the notes"
          else
            echo "no breaking entries in CHANGELOG [$ver]; nothing to splice"
          fi

      - name: Append verification instructions to the notes
        run: |
          cat >> RELEASE_NOTES.md <<EOF

          ## Verification

          Images are signed with cosign (keyless, GitHub OIDC):

          \`\`\`sh
          cosign verify ${IMAGE_PREFIX}-backend:${VERSION} \\
            --certificate-identity-regexp 'https://github.com/${{ github.repository }}/.github/workflows/release.yml.*' \\
            --certificate-oidc-issuer https://token.actions.githubusercontent.com
          \`\`\`

          SPDX SBOMs for the three images and the source tree are attached,
          as is the SDK tarball checksum:

          \`\`\`sh
          sha256sum -c fulla-sdk-${VERSION}-linux-x86_64.tar.gz.sha256
          \`\`\`
          EOF

      - name: Create release with SDK artifacts + SBOMs
        run: |
          gh release create "$GITHUB_REF_NAME" \
            --title "Fulla $GITHUB_REF_NAME" \
            --notes-file RELEASE_NOTES.md \
            "fulla-sdk-${VERSION}-linux-x86_64.tar.gz" \
            "fulla-sdk-${VERSION}-linux-x86_64.tar.gz.sha256" \
            fulla-*-"${VERSION}".spdx.json

      - name: Push nested Go module tag (clients/go/v<version>)
        # Go resolves subdirectory modules from nested tags
        # (go.dev/ref/mod#vcs-version); the root v-tag alone is NOT visible
        # to `go get .../clients/go@vX.Y.Z`. The nested form does not match
        # this workflow's tag trigger (v[0-9]+.[0-9]+.[0-9]+), so it cannot
        # re-trigger the release pipeline.
        run: |
          nested="clients/go/v${VERSION}"
          if git rev-parse -q --verify "refs/tags/${nested}" >/dev/null; then
            echo "tag ${nested} already exists; skipping"
            exit 0
          fi
          git tag "${nested}" "$GITHUB_SHA"
          git push origin "${nested}"

  sdk-python:
    name: Python SDK (PyPI)
    needs: version-check
    # Runs on dispatch too (dry run): version check + build always execute;
    # only the publish step is tag-gated. Secret gating uses job-level env +
    # step-level if because the `secrets` context is unavailable in a
    # job-level `if:` (it would silently evaluate empty).
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    env:
      VERSION: ${{ needs.version-check.outputs.version }}
      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
    steps:
      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"

      - name: Version linkage check (pyproject == cmake == tag)
        # Backstop so a forgotten pyproject bump can never publish a wrong
        # version: version-check already asserted tag == cmake; this asserts
        # pyproject == cmake (tools/clients/regen_clients.py --version-only).
        run: python tools/clients/regen_clients.py --version-only

      - name: Build sdist + wheel
        run: |
          pip install build
          python -m build clients/python

      - name: Publish to PyPI
        if: github.ref_type == 'tag' && env.PYPI_API_TOKEN != ''
        # Plain twine, NOT pypa/gh-action-pypublish: the runner resolves
        # every `uses:` reference during job setup (a step-level `if` does
        # not prevent it), and this repo's action allowlist rejects pypa/* --
        # which failed the whole job at "Set up job" on v1.3.0 and took the
        # always-run version/build steps down with it. Token auth per PyPI's
        # API-token scheme; attestations need trusted publishing and stay off.
        env:
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
        run: |
          pip install twine
          twine check clients/python/dist/*
          twine upload --non-interactive clients/python/dist/*

      - name: Publish skipped (setup hint)
        if: github.ref_type == 'tag' && env.PYPI_API_TOKEN == ''
        run: |
          echo "::notice::PyPI publish skipped: PYPI_API_TOKEN secret is not configured."
          echo "One-time setup: register the fulla-oauth2 project on pypi.org, then"
          echo "add its API token as the PYPI_API_TOKEN repository secret (repo Settings > Secrets)."