From 7ace161f500979d489a09b6d1ece6967530be960 Mon Sep 17 00:00:00 2001 From: Guillaume Lebedel Date: Fri, 30 Oct 2026 10:51:34 +0000 Subject: [PATCH 1/3] ci: publish ADK releases with PyPI trusted publishing --- .github/workflows/release.yaml | 139 +++++++++++++++++++++++++++++++++ RELEASING.md | 72 +++++++++++++++++ 2 files changed, 211 insertions(+) create mode 100644 .github/workflows/release.yaml create mode 100644 RELEASING.md diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml new file mode 100644 index 0000000..eefc9a0 --- /dev/null +++ b/.github/workflows/release.yaml @@ -0,0 +1,139 @@ +name: Publish to PyPI + +on: + push: + tags: + - "v*" + pull_request: + branches: + - main + paths: + - .github/workflows/release.yaml + workflow_dispatch: + inputs: + tag: + description: "Existing release tag to publish (for example, v0.3.0). Run from main." + required: true + type: string + +# Serialize attempts for the same version without interrupting an upload. +concurrency: + group: pypi-${{ inputs.tag || github.ref_name }} + cancel-in-progress: false + +permissions: + contents: read + +jobs: + build: + name: Test and build release + if: github.event_name != 'workflow_dispatch' || github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout release source + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + # Manual runs can publish a tag that predates this workflow. + # Push and PR runs use the event's immutable commit, not a moving tag. + ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.sha }} + fetch-depth: 0 + persist-credentials: false + + - name: Set up uv + uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0 + with: + python-version: "3.12" + enable-cache: false + + - name: Validate release version and source + id: package + env: + EVENT_NAME: ${{ github.event_name }} + RELEASE_TAG: ${{ inputs.tag || github.ref_name }} + run: | + uv run --no-project --python 3.12 python - <<'PY' + import os + import re + import subprocess + import tomllib + from pathlib import Path + + project = tomllib.loads(Path("pyproject.toml").read_text())["project"] + if project["name"] != "stackone-adk": + raise SystemExit("Only stackone-adk may be published by this workflow") + version = project["version"] + if os.environ["EVENT_NAME"] != "pull_request": + tag = os.environ["RELEASE_TAG"] + if not re.fullmatch(r"v[0-9]+\.[0-9]+\.[0-9]+", tag): + raise SystemExit("Release tag must have the form vMAJOR.MINOR.PATCH") + if tag != f"v{version}": + raise SystemExit(f"Tag {tag} does not match package version {version}") + subprocess.run( + ["git", "merge-base", "--is-ancestor", "HEAD", "origin/main"], check=True + ) + with Path(os.environ["GITHUB_OUTPUT"]).open("a") as output: + output.write(f"version={version}\n") + PY + + - name: Install dependencies + run: uv sync --extra dev --locked + + - name: Lint, type check, and test release source + run: | + uv run ruff check . + uv run mypy stackone_adk + uv run pytest -v + + - name: Build distributions + run: uv build --no-sources + + - name: Verify wheel and source distribution installations + env: + PACKAGE_VERSION: ${{ steps.package.outputs.version }} + run: | + for artifact in dist/*.whl dist/*.tar.gz; do + uv run --isolated --no-project --with "$artifact" python -I -c \ + 'import os; from importlib.metadata import version; from stackone_adk import StackOnePlugin; from stackone_ai import StackOneToolSet; assert version("stackone-adk") == os.environ["PACKAGE_VERSION"]; print("Installed stackone-adk", version("stackone-adk"), "with stackone-ai", version("stackone-ai"))' + done + + - name: Upload tested distributions + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: dist + path: | + dist/*.whl + dist/*.tar.gz + if-no-files-found: error + retention-days: 7 + + publish: + name: Publish tested distributions + needs: build + if: >- + github.repository == 'StackOneHQ/stackone-adk-plugin' && + (github.event_name == 'push' || + (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')) + runs-on: ubuntu-latest + timeout-minutes: 10 + environment: + name: pypi + url: https://pypi.org/project/stackone-adk/ + permissions: + id-token: write + steps: + - name: Set up uv + uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0 + with: + enable-cache: false + + - name: Download tested distributions + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: dist + path: dist + + # PyPI exchanges this job's GitHub identity for a short-lived upload token. + # No repository checkout, dependency installation, or long-lived secret here. + - name: Publish with PyPI Trusted Publishing + run: uv publish --trusted-publishing always diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..e5ba1e5 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,72 @@ +# Publishing stackone-adk + +The `Publish to PyPI` workflow tests and builds the selected release commit, then +uploads those tested distributions from a separate job. It authenticates through +PyPI Trusted Publishing; do not add a `PYPI_API_TOKEN` or `UV_PUBLISH_TOKEN` secret. +Pull requests changing the workflow run the build checks without publishing. + +## One-time configuration + +In the existing **stackone-adk** project on PyPI, open **Manage → Publishing** and +add a GitHub Trusted Publisher, or reuse the existing one if these fields match: + +| Field | Value | +| --- | --- | +| Owner | `StackOneHQ` | +| Repository | `stackone-adk-plugin` | +| Workflow filename | `release.yaml` | +| Environment | `pypi` | + +The workflow filename is the filename alone, not its `.github/workflows/` path. +In GitHub, create the `pypi` environment under **Settings → Environments**. Allow +deployments from branch `main` and tags matching `v*`. The branch rule permits +manual recovery runs; the tag rule permits ordinary releases. + +The PyPI configuration is separate from the GitHub environment. Both must match +before an upload can succeed. See the official +[PyPI setup guide](https://docs.pypi.org/trusted-publishers/adding-a-publisher/). + +## Ordinary releases + +1. Merge the version change, updated lockfile, and release changes into `main`. +2. Tag the intended commit with `v` followed by the exact package version and push + that tag. The workflow accepts stable `vMAJOR.MINOR.PATCH` tags only. +3. Watch **Actions → Publish to PyPI**. The workflow rejects a tag that disagrees + with `pyproject.toml` or a commit that is not part of `main`'s history. +4. Confirm both distribution files appear on the version-specific PyPI page. +5. Check installation and imports in a fresh environment, as shown below. + +The workflow must exist at the tagged commit for a tag push to trigger it. For +older commits or a recovery run, use the manual path instead. Never move an +existing release tag or change the contents of an already published version. + +## First release from the existing commit + +The intended `0.3.0` commit predates this workflow. After the workflow is merged and +the PyPI publisher is configured, create the tag at the original commit and run +the workflow from `main` with that existing tag: + +```bash +git fetch origin main --tags +git tag v0.3.0 47b20e6eb90aa7d36a87a0df6720ae37cf1feb44 +git push origin refs/tags/v0.3.0 +gh workflow run release.yaml --repo StackOneHQ/stackone-adk-plugin \ + --ref main -f tag=v0.3.0 +``` + +If the tag already exists, confirm its commit instead of recreating it. Manual +runs check out the tag's code while using the workflow from `main`; they do not +publish whatever happens to be the latest commit on `main`. + +After publishing, verify https://pypi.org/project/stackone-adk/0.3.0/ and run: + +```bash +uv run --isolated --no-project --python 3.12 \ + --with 'stackone-adk==0.3.0' --with 'stackone-ai==3.0.0' \ + python -I -c 'from importlib.metadata import version; from stackone_adk import StackOnePlugin; from stackone_ai import StackOneToolSet; print(version("stackone-adk"), version("stackone-ai"))' +``` + +A package-age policy may temporarily prevent a new release from installing on a +managed device. Wait for the policy window or request an administrator exception; +do not disable endpoint protection. A failed upload due to an unmatched Trusted +Publisher needs the PyPI settings corrected, not a replacement API token. From ff52784499205c298788c05e7d4cea8f84645aa2 Mon Sep 17 00:00:00 2001 From: Guillaume Lebedel Date: Fri, 30 Oct 2026 10:53:49 +0000 Subject: [PATCH 2/3] ci: use current artifact actions with Node 24 --- .github/workflows/release.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index eefc9a0..6ba788f 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -98,7 +98,7 @@ jobs: done - name: Upload tested distributions - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: dist path: | @@ -128,7 +128,7 @@ jobs: enable-cache: false - name: Download tested distributions - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 with: name: dist path: dist From 40b88ae147c91764538fa1feccc8edb264ca2ee5 Mon Sep 17 00:00:00 2001 From: Guillaume Lebedel Date: Fri, 30 Oct 2026 11:25:04 +0000 Subject: [PATCH 3/3] ci: restrict ADK publishing to reviewed main workflow --- .github/workflows/release.yaml | 28 +++++++++++++++------------- RELEASING.md | 31 +++++++++++++++++++------------ 2 files changed, 34 insertions(+), 25 deletions(-) diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 6ba788f..dda86e2 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -1,9 +1,6 @@ name: Publish to PyPI on: - push: - tags: - - "v*" pull_request: branches: - main @@ -35,27 +32,35 @@ jobs: uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 with: # Manual runs can publish a tag that predates this workflow. - # Push and PR runs use the event's immutable commit, not a moving tag. + # PR runs use the event's immutable commit. ref: ${{ github.event_name == 'workflow_dispatch' && format('refs/tags/{0}', inputs.tag) || github.sha }} fetch-depth: 0 persist-credentials: false + - name: Verify release commit is on main + if: github.event_name == 'workflow_dispatch' + run: | + # Check Git history before running any tooling from the selected source. + # Fully qualified refs prevent repository tags from impersonating main. + release_commit=$(git rev-parse --verify 'HEAD^{commit}') + main_commit=$(git rev-parse --verify 'refs/remotes/origin/main^{commit}') + git merge-base --is-ancestor "$release_commit" "$main_commit" + - name: Set up uv uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0 with: python-version: "3.12" enable-cache: false - - name: Validate release version and source + - name: Validate package name and release version id: package env: EVENT_NAME: ${{ github.event_name }} - RELEASE_TAG: ${{ inputs.tag || github.ref_name }} + RELEASE_TAG: ${{ inputs.tag }} run: | - uv run --no-project --python 3.12 python - <<'PY' + uv --no-config run --no-project --python 3.12 python -I - <<'PY' import os import re - import subprocess import tomllib from pathlib import Path @@ -69,9 +74,6 @@ jobs: raise SystemExit("Release tag must have the form vMAJOR.MINOR.PATCH") if tag != f"v{version}": raise SystemExit(f"Tag {tag} does not match package version {version}") - subprocess.run( - ["git", "merge-base", "--is-ancestor", "HEAD", "origin/main"], check=True - ) with Path(os.environ["GITHUB_OUTPUT"]).open("a") as output: output.write(f"version={version}\n") PY @@ -112,8 +114,8 @@ jobs: needs: build if: >- github.repository == 'StackOneHQ/stackone-adk-plugin' && - (github.event_name == 'push' || - (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')) + github.event_name == 'workflow_dispatch' && + github.ref == 'refs/heads/main' runs-on: ubuntu-latest timeout-minutes: 10 environment: diff --git a/RELEASING.md b/RELEASING.md index e5ba1e5..94204f7 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -1,6 +1,7 @@ # Publishing stackone-adk -The `Publish to PyPI` workflow tests and builds the selected release commit, then +Run `Publish to PyPI` manually from `main` with an existing release tag. It tests +and builds the selected release commit, then uploads those tested distributions from a separate job. It authenticates through PyPI Trusted Publishing; do not add a `PYPI_API_TOKEN` or `UV_PUBLISH_TOKEN` secret. Pull requests changing the workflow run the build checks without publishing. @@ -18,9 +19,13 @@ add a GitHub Trusted Publisher, or reuse the existing one if these fields match: | Environment | `pypi` | The workflow filename is the filename alone, not its `.github/workflows/` path. -In GitHub, create the `pypi` environment under **Settings → Environments**. Allow -deployments from branch `main` and tags matching `v*`. The branch rule permits -manual recovery runs; the tag rule permits ordinary releases. +In GitHub, create the `pypi` environment under **Settings → Environments**. Choose +**Selected branches and tags** and allow only the **branch** `main`. Remove any +tag rules, including `v*`. Keep pull-request approval required on `main`. + +This environment restriction is required: it ensures publishing uses the reviewed +workflow on `main`. A tag can contain a different workflow, so allowing release +tags into the environment would let that workflow bypass the source checks. The PyPI configuration is separate from the GitHub environment. Both must match before an upload can succeed. See the official @@ -31,14 +36,16 @@ before an upload can succeed. See the official 1. Merge the version change, updated lockfile, and release changes into `main`. 2. Tag the intended commit with `v` followed by the exact package version and push that tag. The workflow accepts stable `vMAJOR.MINOR.PATCH` tags only. -3. Watch **Actions → Publish to PyPI**. The workflow rejects a tag that disagrees - with `pyproject.toml` or a commit that is not part of `main`'s history. -4. Confirm both distribution files appear on the version-specific PyPI page. -5. Check installation and imports in a fresh environment, as shown below. - -The workflow must exist at the tagged commit for a tag push to trigger it. For -older commits or a recovery run, use the manual path instead. Never move an -existing release tag or change the contents of an already published version. +3. Open **Actions → Publish to PyPI → Run workflow**. Select branch `main` and + enter the tag. Pushing a tag alone does not publish. +4. Watch the run. It checks the selected commit against the explicit remote main + branch before running package tooling, then reads metadata with isolated + Python. It rejects unmerged source or a tag that disagrees with `pyproject.toml`. +5. Confirm both distribution files appear on the version-specific PyPI page. +6. Check installation and imports in a fresh environment, as shown below. + +The selected tag can predate the workflow because the workflow itself runs from +`main`. Never move an existing release tag or change an already published version. ## First release from the existing commit