From a57743e3a3f12a71b8f633bf8b7df91fc2368e1b Mon Sep 17 00:00:00 2001 From: Manfred Riem Date: Wed, 10 Jun 2026 08:19:59 -0500 Subject: [PATCH 1/5] feat: add PyPI publishing workflow and readme metadata - Add readme = "README.md" to pyproject.toml for PyPI project description - Add manual publish-pypi.yml workflow using trusted publishers (OIDC) - Update release.yml install instructions to prefer PyPI The publish workflow is manually triggered after a release, checks out the specified tag, verifies version consistency, builds with uv, and publishes using trusted publishing (no API tokens required). Prerequisites before first use: - Take ownership of the specify-cli PyPI project (#2908) - Create a 'pypi' environment in repo settings - Configure trusted publisher on PyPI for this repo/workflow Closes #2908 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/publish-pypi.yml | 70 ++++++++++++++++++++++++++++++ .github/workflows/release.yml | 8 +++- pyproject.toml | 1 + 3 files changed, 78 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/publish-pypi.yml diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml new file mode 100644 index 0000000000..e5d8ac28fd --- /dev/null +++ b/.github/workflows/publish-pypi.yml @@ -0,0 +1,70 @@ +name: Publish to PyPI + +on: + workflow_dispatch: + inputs: + tag: + description: 'Release tag to publish (e.g., v0.10.1)' + required: true + type: string + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout release tag + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 + with: + ref: ${{ inputs.tag }} + + - name: Verify tag is a release + run: | + TAG="${{ inputs.tag }}" + if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "Error: '$TAG' is not a valid release tag (expected vX.Y.Z)" + exit 1 + fi + + - name: Verify tag matches package version + run: | + TAG_VERSION="${{ inputs.tag }}" + TAG_VERSION="${TAG_VERSION#v}" + PROJECT_VERSION="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')" + if [[ "$TAG_VERSION" != "$PROJECT_VERSION" ]]; then + echo "Error: Tag version ($TAG_VERSION) does not match pyproject.toml version ($PROJECT_VERSION)" + exit 1 + fi + + - name: Install uv + uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5 + + - name: Build package + run: uv build + + - name: Upload build artifacts + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4 + with: + name: dist + path: dist/ + + publish: + needs: build + runs-on: ubuntu-latest + environment: pypi + permissions: + id-token: write + steps: + - name: Download build artifacts + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 + with: + name: dist + path: dist/ + + - name: Install uv + uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5 + + - name: Publish to PyPI + run: uv publish --trusted-publishing always diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b35bc30ec2..7b5683881f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -66,10 +66,16 @@ jobs: ## Install \`\`\`bash - uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@${VERSION} + uv tool install specify-cli@latest specify init my-project \`\`\` + Or install from source: + + \`\`\`bash + uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@${VERSION} + \`\`\` + NOTES_EOF echo "## What's Changed" >> release_notes.md diff --git a/pyproject.toml b/pyproject.toml index f8bdc23f91..463d8d8562 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,6 +2,7 @@ name = "specify-cli" version = "0.10.2.dev0" description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)." +readme = "README.md" requires-python = ">=3.11" dependencies = [ "typer>=0.24.0", From 6fadb04bfb0104cb1d78fbd41938cddeb0e7b902 Mon Sep 17 00:00:00 2001 From: Manfred Riem Date: Wed, 10 Jun 2026 08:42:34 -0500 Subject: [PATCH 2/5] fix: address PR review feedback on publish workflow - Add actions: read permission (required for artifact upload/download) - Move version check after uv install and use uv run python (ensures Python >=3.11 with tomllib is available regardless of runner image) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/publish-pypi.yml | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml index e5d8ac28fd..2b4e6f9420 100644 --- a/.github/workflows/publish-pypi.yml +++ b/.github/workflows/publish-pypi.yml @@ -10,6 +10,7 @@ on: permissions: contents: read + actions: read jobs: build: @@ -28,19 +29,19 @@ jobs: exit 1 fi + - name: Install uv + uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5 + - name: Verify tag matches package version run: | TAG_VERSION="${{ inputs.tag }}" TAG_VERSION="${TAG_VERSION#v}" - PROJECT_VERSION="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')" + PROJECT_VERSION="$(uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')" if [[ "$TAG_VERSION" != "$PROJECT_VERSION" ]]; then echo "Error: Tag version ($TAG_VERSION) does not match pyproject.toml version ($PROJECT_VERSION)" exit 1 fi - - name: Install uv - uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5 - - name: Build package run: uv build @@ -56,6 +57,7 @@ jobs: environment: pypi permissions: id-token: write + actions: read steps: - name: Download build artifacts uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4 From fb6df4cc6fa099b638b7c733b5885cf0ffa3be1e Mon Sep 17 00:00:00 2001 From: Manfred Riem Date: Wed, 10 Jun 2026 15:29:20 -0500 Subject: [PATCH 3/5] fix: use absolute URLs for README images (PyPI compatibility) PyPI does not host images from the repository, so relative paths like ./media/logo.webp render as broken images. Switch to absolute raw.githubusercontent.com URLs so images display on both GitHub and PyPI. Ref: https://github.com/pypi/warehouse/issues/5246 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0a0b4119b2..1d9d7d0887 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@
- Spec Kit Logo + Spec Kit Logo

🌱 Spec Kit

Build high-quality software faster.

@@ -320,7 +320,7 @@ specify init . --force specify init --here --force ``` -![Specify CLI bootstrapping a new project in the terminal](./media/specify_cli.gif) +![Specify CLI bootstrapping a new project in the terminal](https://raw.githubusercontent.com/github/spec-kit/main/media/specify_cli.gif) In an interactive terminal, you will be prompted to select the coding agent integration you are using. In non-interactive sessions, such as CI or piped runs, `specify init` defaults to GitHub Copilot unless you pass `--integration`. You can also proactively specify the integration directly in the terminal: @@ -354,7 +354,7 @@ specify init --integration copilot --ignore-agent-tools Go to the project folder and run your coding agent. In our example, we're using `claude`. -![Bootstrapping Claude Code environment](./media/bootstrap-claude-code.gif) +![Bootstrapping Claude Code environment](https://raw.githubusercontent.com/github/spec-kit/main/media/bootstrap-claude-code.gif) You will know that things are configured correctly if you see the `/speckit.constitution`, `/speckit.specify`, `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` commands available. From 6d15830c028849845fd0839ab21680654eb03ddb Mon Sep 17 00:00:00 2001 From: Manfred Riem Date: Wed, 10 Jun 2026 16:24:04 -0500 Subject: [PATCH 4/5] fix: address second review round - Convert remaining /media/ image path to absolute URL for PyPI - Pin release install to specific version (specify-cli==X.Y.Z) - Align setup-uv to v8.2.0 matching rest of CI Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/publish-pypi.yml | 4 ++-- .github/workflows/release.yml | 2 +- README.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml index 2b4e6f9420..91ef3ef0a8 100644 --- a/.github/workflows/publish-pypi.yml +++ b/.github/workflows/publish-pypi.yml @@ -30,7 +30,7 @@ jobs: fi - name: Install uv - uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5 + uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0 - name: Verify tag matches package version run: | @@ -66,7 +66,7 @@ jobs: path: dist/ - name: Install uv - uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5 + uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0 - name: Publish to PyPI run: uv publish --trusted-publishing always diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7b5683881f..e4af57e0f1 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -66,7 +66,7 @@ jobs: ## Install \`\`\`bash - uv tool install specify-cli@latest + uv tool install specify-cli==${VERSION_NO_V} specify init my-project \`\`\` diff --git a/README.md b/README.md index 1d9d7d0887..4a4c8c63ac 100644 --- a/README.md +++ b/README.md @@ -125,7 +125,7 @@ For detailed step-by-step instructions, see our [comprehensive guide](./spec-dri Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv)! -[![Spec Kit video header](/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv) +[![Spec Kit video header](https://raw.githubusercontent.com/github/spec-kit/main/media/spec-kit-video-header.jpg)](https://www.youtube.com/watch?v=a9eR1xsfvHg&pp=0gcJCckJAYcqIYzv) ## 🌍 Community From 1efe6346a76154ec28e6210827bf2cdf2ce428ef Mon Sep 17 00:00:00 2001 From: Manfred Riem Date: Thu, 11 Jun 2026 12:50:58 -0500 Subject: [PATCH 5/5] fix: address third review round - Use job-level permissions: actions:write on build (for upload-artifact), actions:read on publish (for download-artifact) - Include both @latest and pinned version in release notes - Add note that PyPI may lag behind the GitHub release Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/publish-pypi.yml | 3 ++- .github/workflows/release.yml | 10 +++++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml index 91ef3ef0a8..6cedde6841 100644 --- a/.github/workflows/publish-pypi.yml +++ b/.github/workflows/publish-pypi.yml @@ -10,11 +10,12 @@ on: permissions: contents: read - actions: read jobs: build: runs-on: ubuntu-latest + permissions: + actions: write steps: - name: Checkout release tag uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e4af57e0f1..a22c7c34b5 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -66,16 +66,24 @@ jobs: ## Install \`\`\`bash - uv tool install specify-cli==${VERSION_NO_V} + uv tool install specify-cli@latest specify init my-project \`\`\` + Or pin to this exact release: + + \`\`\`bash + uv tool install specify-cli==${VERSION_NO_V} + \`\`\` + Or install from source: \`\`\`bash uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@${VERSION} \`\`\` + > **Note:** PyPI publishing runs shortly after this release is created. If the PyPI version is not yet available, use the source install command above. + NOTES_EOF echo "## What's Changed" >> release_notes.md