publish.yml

# Generated by reflex-release; do not edit by hand.
# Re-run `uvx reflex-release@0.1.0a4 sync` after changing [tool.reflex-release] in
# pyproject.toml. `uvx reflex-release@0.1.0a4 sync --check` fails when this file drifts.
name: Publish to PyPI

run-name: Publish ${{ inputs.package }} ${{ inputs.version }}

# Publishes one package at one version, in five stages:
#
#   prepare          unprivileged: validates the request against the changelog
#                    (source of truth), branch rules, lockstep invariant and
#                    existing tags, then emits the version, tag and build
#                    directory every later job works from.
#   build            unprivileged: tags the local checkout (the dynamic
#                    versioning backend derives the version from it), builds,
#                    and uploads what it produced as a workflow artifact.
#   custom-build-*   unprivileged: packages configured with a custom
#                    build workflow build there instead of in `build`.
#                    The workflow is this repository's own file, and
#                    uploads its distribution files as artifacts named
#                    after the `artifact-prefix` input it is given.
#   collect          unprivileged: gathers every file the build produced,
#                    verifies each one is this package at this version, extracts
#                    the release notes and writes the checksum manifest the
#                    approver sees.
#   publish          gated by the `pypi` environment — a human reviewer must
#                    approve every upload, alphas included. Holds the only
#                    OIDC (id-token) privilege and runs nothing but
#                    `uv publish` on the pre-built artifact.
#   tag-and-release  only after a successful upload: pushes the tag and
#                    creates the GitHub release. A failed run therefore leaves
#                    no tag behind — fix the problem on top of the changelog
#                    bump and the release-from-changelog workflow retries on
#                    the next push.
#
# Every build job runs before the approval gate and none of them holds a
# credential, so a build that fails — any leg of a matrix included — stops the
# release instead of publishing an incomplete set.
#
# REQUIRED CONFIGURATION:
# - The `pypi` environment MUST have required reviewers configured
#   (Settings -> Environments -> pypi). The publish job asserts this via the
#   API and fails closed when it cannot prove reviewers are configured.
# - PyPI trusted publishing must trust this workflow file (publish.yml) with
#   the `pypi` environment — including when it is called from another
#   workflow (the OIDC job_workflow_ref claim still points at publish.yml).
# - If the `pypi` environment restricts deployment branches, allow
#   main, r/pre-* and r/hotfix/*.
# - Optional: a `.github/scripts/publish/post_build.sh` hook runs after the
#   build with PACKAGE, VERSION, BUILD_DIR and DIST_DIR in the environment —
#   use it for repository-specific artifact checks.
# - Optional: post-release-workflow names a workflow this one dispatches on
#   every published tag, once the release exists.

on:
  workflow_call:
    inputs:
      package:
        description: "Package to publish"
        required: true
        type: string
      version:
        description: "Target version (e.g. 1.2.3 or 1.2.3a1, no v prefix). Empty auto patch-bumps the newest tag — only for packages without a CHANGELOG.md."
        required: false
        type: string
        default: ""
  workflow_dispatch:
    inputs:
      package:
        description: "Package to publish"
        required: true
        type: string
      version:
        description: "Target version (e.g. 1.2.3 or 1.2.3a1, no v prefix). Empty auto patch-bumps the newest tag — only for packages without a CHANGELOG.md."
        required: false
        default: ""

permissions:
  contents: read

# The same per-package group every caller uses on its calling job, so direct
# dispatches and workflow_call publishes of one package are mutually exclusive
# end to end. (A called workflow's top-level concurrency is ignored for
# workflow_call, so this cannot deadlock against the callers' groups.)
concurrency:
  group: publish-${{ inputs.package }}
  cancel-in-progress: false

jobs:
  prepare:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      skipped: ${{ steps.prepare.outputs.skipped }}
      version: ${{ steps.prepare.outputs.version }}
      tag: ${{ steps.prepare.outputs.tag }}
      build_dir: ${{ steps.prepare.outputs.build_dir }}
      prerelease: ${{ steps.prepare.outputs.prerelease }}
      mark_latest: ${{ steps.prepare.outputs.mark_latest }}
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-tags: true
          fetch-depth: 0
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

      - name: Validate against changelog, branch rules and existing tags
        id: prepare
        env:
          PACKAGE: ${{ inputs.package }}
          VERSION: ${{ inputs.version }}
          REF_NAME: ${{ github.ref_name }}
        shell: bash
        run: uvx reflex-release@0.1.0a4 prepare-publish

      # Custom-built packages never reach the `build` job, where this gate
      # normally runs after the lockstep pin rewrites their metadata. They
      # cannot be exact-pin lockstep members, so nothing rewrites theirs
      # and the gate belongs here — still before anything is built.
      - name: Reject development-release dependency pins
        if: >-
          steps.prepare.outputs.skipped != 'true' &&
          contains(fromJson('["xy"]'), inputs.package)
        env:
          PACKAGE: ${{ inputs.package }}
        shell: bash
        run: uvx reflex-release@0.1.0a4 check-dev-pins "$PACKAGE"

  build:
    needs: prepare
    if: >-
      needs.prepare.outputs.skipped != 'true'
      && !contains(fromJson('["xy"]'), inputs.package)
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-tags: true
          fetch-depth: 0
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

      - name: Pin lockstep siblings to exact versions
        env:
          PACKAGE: ${{ inputs.package }}
          VERSION: ${{ needs.prepare.outputs.version }}
        shell: bash
        run: uvx reflex-release@0.1.0a4 pin-lockstep

      # A *.dev dependency pin references an unpublished version, so it must
      # never reach released package metadata. Scoped to the package being
      # published so a dependency can still be released while dependents
      # temporarily dev-pin it. It runs after the lockstep pin, which is what
      # turns a sibling's dev pin into the exact version being released.
      - name: Reject development-release dependency pins
        env:
          PACKAGE: ${{ inputs.package }}
        shell: bash
        run: uvx reflex-release@0.1.0a4 check-dev-pins "$PACKAGE"

      # The dynamic versioning backend derives each package's version from the
      # newest reachable tag with the package's prefix, so tagging HEAD locally
      # is what selects the version being built. The tag is only pushed after a
      # successful upload (tag-and-release job).
      - name: Tag local checkout
        env:
          TAG: ${{ needs.prepare.outputs.tag }}
        shell: bash
        run: git tag "$TAG"

      # --out-dir is absolute so the artifacts land in the repository root
      # regardless of the project layout: a uv workspace member would otherwise
      # build into the workspace root and a standalone package into its own
      # directory.
      - name: Build
        env:
          BUILD_DIR: ${{ needs.prepare.outputs.build_dir }}
        shell: bash
        run: uv build --directory "$BUILD_DIR" --out-dir "$GITHUB_WORKSPACE/dist"

      - name: Upload the built distribution files
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: dist-${{ inputs.package }}--build
          path: dist/*
          if-no-files-found: error
          overwrite: true

  # Repository-supplied build, replacing the `build` job for:
  #   xy
  # A called workflow can hold no more privilege than the calling job
  # grants it, so this runs inside the same unprivileged boundary as
  # `build`: no secrets, no OIDC, and everything it produces is verified
  # by `collect` before the approval gate. Every job it starts has to
  # succeed, so a lost matrix leg stops the release.
  custom-build-build_release_artifacts:
    needs: prepare
    if: >-
      needs.prepare.outputs.skipped != 'true' &&
      contains(fromJson('["xy"]'), inputs.package)
    permissions:
      contents: read
    uses: ./.github/workflows/build_release_artifacts.yml
    with:
      package: ${{ inputs.package }}
      version: ${{ needs.prepare.outputs.version }}
      tag: ${{ needs.prepare.outputs.tag }}
      build-dir: ${{ needs.prepare.outputs.build_dir }}
      artifact-prefix: dist-${{ inputs.package }}--

  # Everything that turns "some files exist" into "these exact files are what
  # the reviewer is approving": the metadata check, the repository's own hook,
  # the release notes and the checksum manifest. One code path, whichever job
  # produced the files.
  collect:
    needs: [prepare, build, custom-build-build_release_artifacts]
    # Exactly one build path runs for a given package, so the others report
    # 'skipped' — which this tolerates while still failing closed on a build
    # that errored, was cancelled, or (in a matrix) lost a single leg.
    if: >-
      !cancelled() && !failure() &&
      needs.prepare.outputs.skipped != 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      # Full history and tags: post_build.sh used to run in the build job, whose
      # checkout has both, and a hook that inspects them must keep working.
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-tags: true
          fetch-depth: 0
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

      # One artifact per build job — a platform matrix uploads one per leg —
      # merged into a single dist/. The `--` in the pattern is what keeps a
      # package from collecting a sibling's artifacts when its name is a prefix
      # of theirs (mypkg vs mypkg-base).
      - name: Download the built distribution files
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          pattern: dist-${{ inputs.package }}--*
          path: dist
          merge-multiple: true

      - name: Flatten the downloaded artifacts
        shell: bash
        run: |
          set -euo pipefail
          # mkdir, because no matching artifact leaves nothing behind at all —
          # verify-dist reports that far better than `find` reports a missing
          # directory.
          mkdir -p dist
          # `uv publish dist/*` uploads files, not directories, so a build
          # workflow that kept its files in a subdirectory is normalized here
          # rather than failing the release over a layout detail. A name
          # collision leaves the directory non-empty and fails the step.
          find dist -mindepth 2 -type f -exec mv -n -t dist -- {} +
          find dist -mindepth 1 -type d -delete
          ls -l dist

      - name: Verify built artifact names and versions
        env:
          PACKAGE: ${{ inputs.package }}
          VERSION: ${{ needs.prepare.outputs.version }}
        shell: bash
        run: uvx reflex-release@0.1.0a4 verify-dist

      - name: Repository-specific post-build checks
        if: hashFiles('.github/scripts/publish/post_build.sh') != ''
        env:
          PACKAGE: ${{ inputs.package }}
          VERSION: ${{ needs.prepare.outputs.version }}
          BUILD_DIR: ${{ needs.prepare.outputs.build_dir }}
          DIST_DIR: dist
        shell: bash
        run: bash .github/scripts/publish/post_build.sh

      - name: Extract release notes from changelog
        env:
          PACKAGE: ${{ inputs.package }}
          VERSION: ${{ needs.prepare.outputs.version }}
          NOTES_PATH: release_notes.md
        shell: bash
        run: uvx reflex-release@0.1.0a4 extract-notes

      # The manifest covers exactly the files that go to PyPI. It lets the
      # gated publish job re-verify (with coreutils only) that what it uploads
      # is byte-identical to what was built and verified here, it is put in
      # front of the approver (job summary), and it is attached to the GitHub
      # release so the record of what a version contains outlives this run.
      - name: Write checksum manifest
        shell: bash
        run: |
          set -euo pipefail
          # Bare filenames, covering exactly the files that go to PyPI: the
          # manifest is attached to the GitHub release, so `sha256sum -c` has
          # to work in a directory holding the downloaded artifacts.
          (cd dist && sha256sum -- *) > SHA256SUMS
          {
            echo "### Artifacts awaiting approval"
            echo
            echo '```'
            cat SHA256SUMS
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"

      - name: Upload artifacts for the gated publish
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: publish-${{ inputs.package }}
          path: |
            dist/*
            release_notes.md
            SHA256SUMS
          if-no-files-found: error
          overwrite: true

  # The human approval gate: this job targets the `pypi` environment, whose
  # required reviewers must approve before it starts. It holds the only OIDC
  # privilege and deliberately runs no repository code and resolves no script
  # dependencies — it only uploads the artifact collected above.
  publish:
    needs: [prepare, collect]
    # The status function is load-bearing. With none, GitHub applies an
    # implicit success() evaluated over the whole transitive dependency
    # closure rather than the direct needs — and exactly one build path ever
    # runs, so the skipped one reaches this job straight through the `collect`
    # written to absorb it and the upload silently never happens.
    if: >-
      !cancelled() && needs.collect.result == 'success' &&
      needs.prepare.outputs.skipped != 'true'
    runs-on: ubuntu-latest
    environment:
      name: pypi
    permissions:
      id-token: write
      # Reading the environment's protection rules needs repository read access
      # on GITHUB_TOKEN (contents) plus actions: read.
      actions: read
      contents: read
    steps:
      - name: Require a human-approval gate on the pypi environment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ALLOW_SELF_REVIEW: "true"
        shell: bash
        run: |
          set -euo pipefail
          # Fail closed: uploads must never run unattended. If this job started
          # without reviewers configured on the pypi environment, nothing paused
          # it — refuse to publish and tell the admins how to fix it. The two
          # failure modes get distinct messages so a token scope problem is not
          # mistaken for missing reviewers.
          if ! environment=$(gh api "repos/${GITHUB_REPOSITORY}/environments/pypi" 2>"$RUNNER_TEMP/gh_api_error.txt"); then
            echo "::error::Could not read the pypi environment's protection rules ($(tail -n1 "$RUNNER_TEMP/gh_api_error.txt")); refusing to publish unattended. This is a token or configuration problem, not a missing-reviewers problem: the job needs contents: read and actions: read on GITHUB_TOKEN, and the pypi environment must exist."
            exit 1
          fi
          rules=$(jq -c '[.protection_rules[]?.type]' <<<"$environment")
          if [[ "$rules" != *'"required_reviewers"'* ]]; then
            echo "::error::The pypi environment has no required reviewers. Every PyPI upload must be approved by a human: add required reviewers to the pypi environment (Settings -> Environments) and re-run."
            exit 1
          fi
          # Reviewers alone are not a two-person rule: unless self-review is
          # prevented, whoever triggered the release can approve their own
          # upload. Whether that is acceptable is a policy choice, so it is
          # configured (allow-self-review) rather than assumed.
          if [[ "$ALLOW_SELF_REVIEW" == "true" ]]; then
            echo "pypi environment protection rules: $rules"
            echo "Self-review is permitted (allow-self-review); the environment's reviewer list is the control over who can approve this upload."
            exit 0
          fi
          # tostring, not `// "unknown"`: jq's alternative operator treats a
          # literal false as absent, which would turn the case this check exists
          # for into a warning.
          self_review=$(jq -r '[.protection_rules[]? | select(.type == "required_reviewers") | .prevent_self_review] | first | tostring' <<<"$environment")
          # Strict mode is opt-in, so anything short of a proven "true" fails:
          # a warning nobody reads is not a two-person rule, and "the API did
          # not say" is indistinguishable from "self-review is allowed".
          if [[ "$self_review" != "true" ]]; then
            echo "::error::This repository sets allow-self-review = false, but the pypi environment does not report that self-review is prevented (prevent_self_review: $self_review), so the person who triggered this release could approve their own upload. Enable 'Prevent self-review' on the pypi environment (Settings -> Environments -> pypi) and re-run. If your GitHub deployment cannot report that setting, set allow-self-review = true to make the reviewer list the control."
            exit 1
          fi
          echo "pypi environment protection rules: $rules (prevent_self_review: $self_review)"

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

      - name: Download built artifacts
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: publish-${{ inputs.package }}

      - name: Verify artifact integrity
        shell: bash
        run: cd dist && sha256sum -c ../SHA256SUMS

      # --check-url makes a retried run skip files that already made it to PyPI
      # (e.g. when the upload succeeded but tagging failed), instead of erroring
      # on the duplicate upload.
      - name: Publish
        shell: bash
        run: uv publish --check-url https://pypi.org/simple/ dist/*

  tag-and-release:
    needs: [prepare, publish]
    # The same transitive implicit success() reaches this job through
    # `publish`, so it needs a status function of its own. Not `!failure()`:
    # a skipped publish is neither failed nor cancelled, and tolerating it
    # would push the tag for a release that uploaded nothing.
    if: >-
      !cancelled() && needs.publish.result == 'success'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      actions: write
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0

      # The same artifact the approval covered: the release notes and the
      # checksum manifest of exactly what was uploaded.
      - name: Download release notes and checksums
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: publish-${{ inputs.package }}

      - name: Push tag
        env:
          TAG: ${{ needs.prepare.outputs.tag }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        shell: bash
        run: uvx reflex-release@0.1.0a4 push-tag

      - name: Create GitHub release
        env:
          TAG: ${{ needs.prepare.outputs.tag }}
          PACKAGE: ${{ inputs.package }}
          VERSION: ${{ needs.prepare.outputs.version }}
          PRERELEASE: ${{ needs.prepare.outputs.prerelease }}
          MARK_LATEST: ${{ needs.prepare.outputs.mark_latest }}
          NOTES_PATH: release_notes.md
          CHECKSUMS_PATH: SHA256SUMS
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        shell: bash
        run: uvx reflex-release@0.1.0a4 create-release

      # One dispatch per published tag, on the tag itself, after the upload,
      # the tag and the GitHub release: the workflow sees exactly the tree that
      # was published. It must declare workflow_dispatch inputs named
      # tag, package, version.
      - name: Trigger the post-release workflow
        env:
          TAG: ${{ needs.prepare.outputs.tag }}
          PACKAGE: ${{ inputs.package }}
          VERSION: ${{ needs.prepare.outputs.version }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        shell: bash
        run: uvx reflex-release@0.1.0a4 post-release