Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 141 additions & 0 deletions .github/workflows/release.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
name: Publish to PyPI

on:
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.
# 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 package name and release version
id: package
env:
EVENT_NAME: ${{ github.event_name }}
RELEASE_TAG: ${{ inputs.tag }}
run: |
uv --no-config run --no-project --python 3.12 python -I - <<'PY'
import os
import re
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}")
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@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.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 == '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@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
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
79 changes: 79 additions & 0 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Publishing stackone-adk

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.

## 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**. 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
[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. 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

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.
Loading