Inline publish step into release.yml to fix PyPI attestations (#173)

* chore(release): v0.10.0

* fix(release): inline build+publish into release.yml; remove workflow_call chain

PyPI Trusted Publishing attestations are incompatible with reusable
workflow chains. When release.yml invoked publish.yml via workflow_call,
the OIDC token's job_workflow_ref pointed at publish.yml while the
Sigstore cert's Build Config URI pointed at release.yml; PyPI ties both
to the same publisher and rejected the attestation as a 400. This bit
v0.10.0 (auth passed, attestation verification failed) -- see
pypa/gh-action-pypi-publish#166 and PyPI's docs on reusable workflows.

PR #171 fixed the older 'stale checkout SHA' bug, which let the build
correctly produce flights-0.10.0.* -- but exposed this attestation issue
as the next layer. Adding release.yml as a second Trusted Publisher on
PyPI doesn't help because PyPI still matches the OIDC token's
job_workflow_ref (publish.yml) to the publisher and validates the cert
(release.yml) against that publisher.

Fix:
- release.yml: inline the build/twine/upload steps as a new 'publish' job
  with environment: pypi and id-token: write. Run the test matrix first
  via test.yml workflow_call (no OIDC, so no attestation concern).
- publish.yml: drop the workflow_call entry point and the 'ref' input.
  Keep the release: published and workflow_dispatch entry points -- those
  are now exclusively for manual recovery, TestPyPI smoke tests, and the
  manual GitHub Release fallback.
- docs/guides/release.md: document the new architecture, the PyPI
  prerequisite (two Trusted Publishers: release.yml AND publish.yml), and
  add a troubleshooting entry for the attestation failure.

Required PyPI config change: add release.yml as a Trusted Publisher
(workflow=release.yml, environment=pypi). Keep publish.yml's existing
publisher for manual paths.

* ci(publish): guard release-event publish to humans; drop duplicate test/lint steps

Address review feedback on PR #173:

1. Duplicate-publish guard. release.yml now publishes inline AND creates the
   tag/GitHub Release via the bot. Guard publish.yml's pypi-publish job so a
   release event only auto-publishes when the release was created by a human
   (github.actor != github-actions[bot]); workflow_dispatch publishes only
   when the operator selects the pypi environment. This prevents a second,
   racing publish that would 400 with "File already exists" if a release-event
   path ever fires (e.g. if release.yml is switched to a PAT for branch
   protection). The workflow_dispatch recovery path and human-created-release
   fallback both still work.

2. Remove the single-version "Run tests" step (and the equally redundant ruff
   "Check code quality" step) from publish.yml's release-build job. Both are
   already covered by the test.yml matrix that gates the job via needs: [test]
   (lint.yml + railway-build + the 4-version pytest matrix). Apply the same
   cleanup to release.yml's inline publish job for consistency. release-build
   and the inline publish job now just build, twine-check, and publish.

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

.github/workflows/publish.yml

@@ -1,5 +1,16 @@
 name: Upload Python Package
 
+# Triggers:
+# - release: published    -> auto-publish when a GH Release is created manually
+#                            (e.g. via the manual fallback in docs/guides/release.md)
+# - workflow_dispatch     -> manual publish, used for TestPyPI smoke tests or
+#                            recovery (e.g. shipping a tag that release.yml failed
+#                            to publish). Pick the tag/branch in the dispatch UI.
+#
+# This workflow is NOT called from release.yml -- release.yml inlines its own
+# publish steps. See docs/guides/release.md for the rationale (PyPI Trusted
+# Publishing attestations are incompatible with reusable workflow chains).
+
 on:
   release:
     types: [ published ]
@@ -13,17 +24,6 @@ on:
         options:
         - testpypi
         - pypi
-  workflow_call:
-    inputs:
-      environment:
-        description: 'Environment to publish to (pypi or testpypi)'
-        required: false
-        default: 'pypi'
-        type: string
-      ref:
-        description: 'Git ref (tag/branch/SHA) to build from. Required when called from release.yml so the build picks up the bump commit, not the caller-event SHA.'
-        required: false
-        type: string
 
 permissions:
   contents: read
@@ -33,17 +33,13 @@ permissions:
 jobs:
   test:
     uses: ./.github/workflows/test.yml
-    with:
-      ref: ${{ inputs.ref }}
 
   release-build:
     needs: [ test ]
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.ref || github.ref }}
 
       - name: Install uv
         uses: astral-sh/setup-uv@v7
@@ -56,14 +52,6 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras
 
-      - name: Run tests
-        run: uv run pytest -v --ignore=tests/search/ -k "not test_search_dates_round_trip"
-
-      - name: Check code quality
-        run: |
-          uv run ruff format --check .
-          uv run ruff check .
-
       - name: Build release distributions
         run: uv build
 
@@ -80,7 +68,12 @@ jobs:
     runs-on: ubuntu-latest
     needs:
       - release-build
-    if: ${{ github.event_name == 'release' || inputs.environment == 'pypi' }}
+    # Only auto-publish on release events created by humans (manual fallback).
+    # release.yml publishes inline and creates its tag/Release via the bot, so
+    # excluding github-actions[bot] prevents a second, racing publish that would
+    # 400 with "File already exists". workflow_dispatch publishes only when the
+    # operator explicitly selects the pypi environment.
+    if: ${{ (github.event_name == 'workflow_dispatch' && inputs.environment == 'pypi') || (github.event_name == 'release' && github.actor != 'github-actions[bot]') }}
     permissions:
       id-token: write
 

.github/workflows/release.yml

@@ -229,21 +229,58 @@ jobs:
             cat release_notes.md
           } >> "$GITHUB_STEP_SUMMARY"
 
-  publish:
+  # Run the standard test suite against the new tag before publishing.
+  # Called via workflow_call (not publish), so no OIDC/attestation concerns.
+  test:
     needs: release
     if: ${{ needs.release.outputs.did_release == 'true' }}
-    uses: ./.github/workflows/publish.yml
+    uses: ./.github/workflows/test.yml
     with:
-      environment: pypi
-      # Build from the new tag, not the caller-event SHA. workflow_call
-      # inherits the parent's github.sha (the SHA at release-dispatch time,
-      # before the bump commit lands), so without this the publish job would
-      # rebuild the previous version and PyPI would reject it as duplicate.
       ref: ${{ needs.release.outputs.tag }}
+
+  publish:
+    needs: [ release, test ]
+    if: ${{ needs.release.outputs.did_release == 'true' }}
+    runs-on: ubuntu-latest
     permissions:
       contents: read
-      checks: write
-      pull-requests: write
       id-token: write
-    secrets: inherit
+    environment:
+      name: pypi
+      url: https://pypi.org/p/flights
+    steps:
+      # IMPORTANT: build and publish steps live here (inline) rather than
+      # invoking publish.yml via workflow_call. PyPI's Trusted Publishing
+      # attestations are incompatible with reusable workflow chains -- the
+      # OIDC token's job_workflow_ref points at the called workflow while
+      # the Sigstore cert's Build Config URI points at the top-level
+      # workflow. PyPI ties both to the same publisher, so chained
+      # publishes always fail attestation verification.
+      # See https://docs.pypi.org/trusted-publishers/troubleshooting/#reusable-workflows-on-github
+      - name: Checkout release tag
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.release.outputs.tag }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Build release distributions
+        run: uv build
+
+      - name: Check package
+        run: uv run twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
 

docs/guides/release.md

@@ -5,20 +5,34 @@ on push to `main`; cutting a release is always an explicit, one-click action.
 
 ## Overview
 
-The release pipeline is two workflows:
+The release pipeline is two independent workflows:
 
 | Workflow | File | Trigger |
 | --- | --- | --- |
 | **Release** | `.github/workflows/release.yml` | `workflow_dispatch` only |
-| **Upload Python Package** | `.github/workflows/publish.yml` | `release: published`, `workflow_dispatch`, `workflow_call` |
-
-`release.yml` bumps the version in `pyproject.toml`, refreshes `uv.lock`,
-commits to `main`, creates an annotated tag and GitHub Release, then calls
-`publish.yml` to build and upload to PyPI via Trusted Publishing.
-
-`publish.yml` can also be triggered independently — by publishing a GitHub
-Release manually, or via `workflow_dispatch` (defaults to TestPyPI for
-safe smoke tests).
+| **Upload Python Package** | `.github/workflows/publish.yml` | `release: published`, `workflow_dispatch` |
+
+`release.yml` is the end-to-end release pipeline: it bumps the version in
+`pyproject.toml`, refreshes `uv.lock`, commits to `main`, creates an annotated
+tag and GitHub Release, runs the full test matrix against the new tag, and
+builds + uploads to PyPI via Trusted Publishing — all inline, no chained
+workflow.
+
+`publish.yml` is a standalone publish workflow used for:
+- **Manual recovery** — if `release.yml`'s publish step ever fails, dispatch
+  `publish.yml` on the failed tag (`environment: pypi`) to ship it.
+- **Manual GitHub Release** — if you create a release in the UI from an
+  existing tag, the `release: published` trigger picks it up and publishes.
+- **TestPyPI smoke tests** — `workflow_dispatch` with `environment: testpypi`.
+
+> **Why two workflows instead of one reusable?** PyPI's Trusted Publishing
+> attestations are incompatible with reusable workflow chains
+> ([pypa/gh-action-pypi-publish#166](https://github.com/pypa/gh-action-pypi-publish/issues/166)).
+> When `release.yml` calls `publish.yml` via `workflow_call`, the OIDC token's
+> `job_workflow_ref` points at `publish.yml` while the Sigstore cert's
+> `Build Config URI` points at `release.yml`; PyPI ties both to the same
+> publisher and rejects the attestation. Inlining the publish step into
+> `release.yml` sidesteps this entirely.
 
 ## Cutting a release
 
@@ -65,14 +79,21 @@ modify `pyproject.toml`.
 
 These need to be in place once on the GitHub side:
 
-* **PyPI Trusted Publisher** for the `flights` project, bound to this repo
-  and the `pypi` environment. `publish.yml` requests an OIDC token via
-  `id-token: write` and uses `pypa/gh-action-pypi-publish`.
+* **PyPI Trusted Publishers** for the `flights` project, both bound to this
+  repo and the `pypi` environment:
+  * `release.yml` — used by the automated end-to-end release flow
+  * `publish.yml` — used by manual recovery, `release: published`, and
+    TestPyPI dispatch
+  
+  Configure both at
+  [pypi.org/manage/project/flights/settings/publishing/](https://pypi.org/manage/project/flights/settings/publishing/).
+  Set Environment name to `pypi` on both.
 * **Branch protection on `main`** must permit pushes from `github-actions[bot]`.
   If protection blocks the bot, the release workflow's push will fail; switch
   the checkout step's `token:` to a PAT secret instead.
 * **Workflow permissions**: `release.yml` requires `contents: write` (already
-  declared at the workflow level).
+  declared at the workflow level) and `id-token: write` on the `publish`
+  job for OIDC.
 
 ## Troubleshooting
 
@@ -88,10 +109,26 @@ These need to be in place once on the GitHub side:
 * **Release notes look wrong on first run** — the workflow walks back to the
   last commit whose subject starts with `Bump version`. If you've changed
   that convention, edit `release.yml`'s "Determine commit range" step.
+* **PyPI returns 400 "Invalid attestations supplied"** with cert URI mismatch
+  — the publish job is running via a `workflow_call` chain (the original
+  bug). Make sure the publish job is defined inline in `release.yml`, not
+  invoked via `uses: ./.github/workflows/publish.yml`. As a one-time recovery
+  for the failed tag, dispatch `publish.yml` standalone on that tag.
 
 ## Manual fallback
 
-If the workflow is broken and a release is urgent, you can still:
+If `release.yml`'s publish step fails after the tag and GitHub Release have
+already been created (e.g. transient PyPI outage), recover with:
+
+1. Actions → **Upload Python Package** → Run workflow
+2. **Branch dropdown**: switch to the failed tag (e.g. `vX.Y.Z`)
+3. `environment`: `pypi`
+4. Run
+
+This dispatches `publish.yml` standalone and uploads the same tag's artifact.
+
+If the entire `release.yml` workflow is broken and a release is urgent, you
+can also:
 
 1. Bump the version in `pyproject.toml` and `uv.lock` on a branch, merge to
    `main`.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flights"
-version = "0.9.0"
+version = "0.10.0"
 description = "A Python wrapper for Google Flights API"
 authors = [
     { name = "Punit Arani", email = "punitsai36@gmail.com" }