[Feature Request]: Automated Python Package Versioning in CI/CD

[bamr87]

Automate SemVer versioning for this repo via GitHub Actions — increment major/minor/patch from commit messages, commit the updated version file, tag the release, and optionally publish to PyPI.

Intake found this request is largely obsolete. It was filed 495 days ago, and in the meantime .github/workflows/claude-release.yml shipped and does most of what is asked. Two of the original acceptance criteria are now moot or contradicted by the repo's current documented design, and one rests on a premise that is false for this repository: GitHubAI ships no Python package, so there is nothing to version as a distribution and nothing to publish to PyPI. What remains is one small trigger gap and one product decision.

Context

bamr87/githubai is a reusable GitHub Actions / prompt framework consumed by git ref (uses: bamr87/githubai/.github/workflows/claude-release.yml@main), not a distributable Python artifact. Its pyproject.toml says so in its own first line:

# GitHubAI ships no Python package; this file configures the dev tooling for
# the framework's self-tests (config loader + structure validation).

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra"

[tool.ruff]
line-length = 120
extend-exclude = ["tools/unwrap-prose.py"]

There is no [project] table, no setup.py, and no build backend. The repo does carry a repo-level VERSION file (1.0.0-alpha.1), which is the thing worth versioning — and which claude-release.yml already manages.

Reproduction

Not a defect, so there is no failure to reproduce. The relevant observation is what already exists in the repository at main @ ab0ca8a:

$ ls .github/workflows/
ci.yml                 claude-implement.yml   claude-release.yml   claude-triage.yml
claude-auto-merge.yml  claude-maintenance.yml claude-review.yml    claude.yml
markdown-oneline.yml

$ cat VERSION
1.0.0-alpha.1

$ ls CHANGELOG.md
ls: cannot access 'CHANGELOG.md': No such file or directory

claude-release.yml's own header states its two modes:

# GitHubAI - release automation. Two modes:
#   prepare (workflow_dispatch): Claude inspects commits since the last tag,
#     picks the semver bump, updates VERSION and CHANGELOG.md, and opens a
#     release PR through the normal review lane.
#   publish (tag push v*): Claude drafts categorized release notes from the
#     commit range and creates the GitHub Release (draft by default).

on:
  push:
    tags: ["v*"]
  workflow_dispatch:
    inputs:
      bump: { default: auto, type: choice, options: [auto, major, minor, patch] }
  workflow_call:
    ...

And docs/workflows.md:43-47 documents it, including a deliberate design constraint:

Behavior: publish = categorized release notes from the tag range → GitHub release (draft per config). Prepare = pick the semver bump from commits (or honor the input), update VERSION/CHANGELOG.md on a branch, open a release: vX.Y.Z PR. Tags are never created by automation — pushing the tag stays a human act.

The original acceptance criteria, re-scored against today's main

#	Original criterion	Status
1	Workflow triggers correctly on pushes to main	❌ genuine gap — prepare mode is workflow_dispatch / workflow_call only; there is no push: branches: [main] trigger
2	Version increment logic interprets commit message tags	⚠️ implemented differently — bump: auto has Claude infer the bump from the commit range, rather than parsing literal [major] / [minor] markers
3	Updated versions are committed, tagged, and pushed automatically	⛔ deliberately refused — the repo documents "tags are never created by automation". Versions are committed on a branch via a release PR; a human merges and tags
4	Documentation on usage included in the README	✅ met — documented in docs/workflows.md, with docs/ linked from README.md
5	Optionally publish to PyPI	⛔ not applicable — no Python package exists to publish

Environment

key	value
repo / ref	bamr87/githubai @ main ab0ca8a
detected stack	python
runner	Linux 6.17.0-1022-azure x86_64
captured	2026-08-16 08:10 UTC
python3	3.12.3
node / npm	v22.23.2 / 10.9.8
ruby	3.2.3 · go 1.24.13 · cargo 1.97.1
sandbox phases	clone ✅ 1s · python-venv ✅ 3s · python-install ✅ 0s · python-test ❌ 127 · python-lint ❌ 127 · screenshot ⏭

The two ❌ phases are harness bugs, not repository failures — see the intake comment. tools/issue-evidence.sh builds the interpreter path relative to the output directory and then cds into the workspace before using it, so .venv/bin/python cannot resolve and every Python repo in the fleet reports exit 127 for python-test and python-lint. Nothing is known to be wrong with this repo's test suite; intake was unable to execute it.

Expected vs actual

Expected (as originally requested): a push to main automatically bumps the version per commit-message tags, commits, tags, and publishes the Python package.

Actual (today): a maintainer dispatches claude-release.yml (or another workflow calls it); Claude reads the commits since the last tag, chooses the bump, writes VERSION and CHANGELOG.md on a branch, and opens a release: vX.Y.Z PR into the normal review lane. A human merges and pushes the tag; the tag push then triggers publish mode, which drafts categorized notes and creates a draft GitHub Release. No package is published anywhere, because none is built.

The delta between the two is therefore one missing trigger plus two intentional design differences — not a missing feature.

Scope

rank	file	why
1	.github/workflows/claude-release.yml	the existing implementation; the only change in scope would be adding a push: branches: [main] trigger for prepare mode (guarded so it does not fire on the release PR's own merge)
2	docs/workflows.md L43-47	documents the current behaviour and the "tags stay a human act" rule — must be updated if that rule changes
3	CHANGELOG.md (absent)	claude-release.yml claims to update it, but the file does not exist in the repo. Small real inconsistency worth closing either way
4	VERSION	1.0.0-alpha.1 — the artifact actually being versioned
5	pyproject.toml	establishes that no Python package exists; only relevant as the evidence that criteria 5 is void

Out of scope, confirmed: bumpversion, Poetry, PyPI publishing, and any [project] packaging metadata. Adding packaging to make the original request satisfiable would be a much larger, separate proposal.

Acceptance criteria

This issue is blocked pending a decision (see the intake comment) — the criteria below are what I would apply under the recommended option.

• A decision is recorded on the comment below: close as substantially delivered, narrow to the trigger gap, or migrate to the fleet's release-please standard.
• If narrowed: claude-release.yml gains a push: branches: [main] trigger for prepare mode, guarded so merging a release: vX.Y.Z PR does not immediately open another one — verified by merging a normal PR (a release PR opens) and then merging that release PR (no second release PR opens).
• docs/workflows.md is updated to describe whatever trigger set ends up shipping, and the "tags are never created by automation" sentence still matches reality.
• CHANGELOG.md exists, or the reference to it in claude-release.yml is removed — checked by ls CHANGELOG.md agreeing with grep -n CHANGELOG .github/workflows/claude-release.yml.
• actionlint passes on the modified workflow.
• A test asserts the trigger guard (e.g. a workflow-condition unit check or a documented dry-run), failing before the change and passing after.
• The issue title is corrected — it says "Python Package Versioning", which this repo does not do.

References

• Existing implementation: .github/workflows/claude-release.yml
• Its documentation: docs/workflows.md §claude-release.yml
• Evidence that no package exists: pyproject.toml (header comment)
• Fleet release standard this repo does not use: docs/RELEASES.md · tools/adopt-release.sh · bamr87/.github → release-please.yml
• Live example of the fleet standard working under the same repo settings: https://github.com/bamr87/zer0-image-generator/actions/workflows/release.yml
• SemVer spec: https://semver.org/
• Registry entry: _data/projects.yml → githubai (category full-stack-ai, active)

---

Original report by @bamr87

Describe your feature request clearly.

Description:
Automate Python package versioning adhering to Semantic Versioning (SemVer) standards using GitHub Actions. The CI/CD pipeline should automatically increment versions (major, minor, patch) based on commit messages containing specific tags (e.g., [major], [minor], defaults to patch).

Proposed Implementation:

• Utilize tools such as bumpversion or Poetry to handle version increments.
• Integrate a GitHub Actions workflow that detects specific tags in commit messages to trigger version bumps.
• Automatically commit updated version files, tag releases, and optionally publish to PyPI.

Benefits:

• Ensures consistent and error-free version management.
• Reduces manual intervention, increasing efficiency.
• Provides clear traceability through commit messages and tags.

Acceptance Criteria:

• Workflow triggers correctly on pushes to main.
• Version increment logic correctly interprets commit message tags.
• Updated versions are committed, tagged, and pushed automatically.
• Documentation on usage included in the repo's README.

[bamr87]

🔬 Evidence bundle

Built by tools/issue-evidence.sh in an isolated virtual environment:
a fresh clone of bamr87/githubai, its own toolchain install, and the
project's own lint / test / build. Everything below is observed output,
not inference.

key	value
repo	bamr87/githubai
issue	#69
ref	main @ ab0ca8a
detected stack	python
runner	Linux 6.17.0-1022-azure x86_64
captured	2026-08-16 08:10 UTC
node	v22.23.2
npm	10.9.8
python3	Python 3.12.3
ruby	ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux-gnu]
shellcheck	ShellCheck - shell script analysis tool
go	go version go1.24.13 linux/amd64

Results

phase	result	time	detail
clone	✅ pass	1s	exit 0
python-venv	✅ pass	3s	exit 0
python-install	✅ pass	0s	exit 0
python-test	❌ fail	0s	exit 127
python-lint	❌ fail	0s	exit 127
screenshot	⏭ skipped	0s	no built static output to serve

$ bash -lc cd '.evidence/githubai-69/workspace' && '.evidence/githubai-69/workspace/.venv/bin/python' -m pytest -q
bash: line 1: .evidence/githubai-69/workspace/.venv/bin/python: No such file or directory

Artifact: logs and the full sandbox are attached to this workflow run as the issue-evidence-bundles artifact.

---

Analysis

First: the two red phases are a bug in the hub's evidence harness, not in this repo

Before drawing any conclusion from python-test ❌ 127 and python-lint ❌ 127, I checked whether the venv the harness said it built actually exists. It does:

$ ls .evidence/githubai-69/workspace/.venv/bin
Activate.ps1  activate  activate.csh  activate.fish  pip  pip3  pip3.12
python -> python3   python3 -> /usr/bin/python3   python3.12 -> python3

The interpreter is right there. The harness cannot find it because of a relative-path bug in tools/issue-evidence.sh — WS is a relative path, and phase_python() composes the interpreter as ${WS}/.venv/bin/python and then runs it after cd '${WS}':

# tools/issue-evidence.sh:287-294
local pip="${WS}/.venv/bin/pip" py="${WS}/.venv/bin/python"
...
run_sh python-test test.log "cd '${WS}' && '${pip}' install pytest >/dev/null 2>&1; \
'${py}' -m pytest -q"

After the cd, .evidence/githubai-69/workspace/.venv/bin/python resolves against the workspace itself, so the shell looks for …/workspace/.evidence/githubai-69/workspace/.venv/bin/python. Hence 127. I confirmed it live — a sanctioned --rerun reproduces it exactly, and the same defect is present in the rerun path at L624-625:

$ tools/issue-evidence.sh --repo bamr87/githubai --issue 69 --rerun --out .evidence/githubai-69 --cmd 'python3 -m pytest -q'
  · run   python-test-rerun: bash -lc cd '…/workspace' && '…/workspace/.venv/bin/python' -m pytest -q
  ·       python-test-rerun → fail (127) in 0s

Two consequences worth acting on separately from this issue:

1. python-test and python-lint fail with 127 for every Python repo in the fleet, always — the results are meaningless, not informative.
2. python-install is a false green. Line 288-290 has the same broken ${pip} path but ends in || true, so it reports exit 0 having installed nothing. That is worse than the red phases, because it reads as success.

The fix is to resolve WS to an absolute path once (WS_ABS="$(cd "${WS}" && pwd)"), or to drop the cd and use ./.venv/bin/…. I have not filed this — it is out of this issue's scope and this tier does not open issues. It wants its own ticket against bamr87/bamr87, and it should be a high one, since it silently degrades intake evidence for every Python project.

I could not run this repo's tests. python3 -m pytest on the system interpreter reports No module named pytest, and installing into the sandbox venv was refused by this runner's permission layer. So: no claim either way about bamr87/githubai's test health. Nothing observed suggests a problem; nothing was verified.

The substantive finding: the request is largely already delivered

.github/workflows/claude-release.yml exists and its header describes exactly the automation this issue asked for 495 days ago:

prepare (workflow_dispatch): Claude inspects commits since the last tag, picks the semver bump, updates VERSION and CHANGELOG.md, and opens a release PR through the normal review lane.
publish (tag push v*): Claude drafts categorized release notes from the commit range and creates the GitHub Release (draft by default).

Scoring the original acceptance criteria against today's main: criterion 4 (docs) is met in docs/workflows.md:43-47; criterion 2 is implemented differently (bump: auto infers the bump from the commit range rather than parsing literal [major]/[minor] markers); criterion 1 is a genuine remaining gap — prepare mode has no push: branches: [main] trigger, only workflow_dispatch and workflow_call.

Criteria 3 and 5 cannot be satisfied as written:

• Criterion 3 is deliberately refused by the current design. docs/workflows.md states plainly: "Tags are never created by automation — pushing the tag stays a human act." The issue asks for versions to be "committed, tagged, and pushed automatically". Those are in direct conflict, and no evidence can settle which one you want.
• Criterion 5 has a false premise. The issue is titled "Automated Python Package Versioning" and asks to "optionally publish to PyPI". This repo has no Python package. Its pyproject.toml opens with the line "GitHubAI ships no Python package; this file configures the dev tooling for the framework's self-tests" — there is no [project] table, no setup.py, no build backend. GitHubAI is distributed by git ref (uses: bamr87/githubai/…@main). There is nothing to bump-and-publish; the only versionable artifact is the repo-level VERSION file (1.0.0-alpha.1), which claude-release.yml already manages.

One small real inconsistency, independent of the decision: claude-release.yml says it updates CHANGELOG.md, but ls CHANGELOG.md → No such file or directory.

Label overrides

Priority: computed P1 → applied P3. The score of 58 was computed largely from age (495 days) and CI-related keywords. Age is a poor urgency proxy here: the functionality the issue requests substantially shipped in the interim, so there is no user-visible gap and nothing is blocked. What is left is a trigger tweak and a decision about an obsolete ticket. Ranking that P1 would push it ahead of genuinely-red items in the same queue.

ci stands — the remaining work is a workflow change. size:s stands — adding one guarded trigger. Assignee bamr87 as computed.

⛔ Exit: agent:blocked

Three of the five acceptance criteria are moot, contradicted, or premised on a package that does not exist. Handing this to tier 2 as written would produce a PR implementing bumpversion and PyPI publishing for a repo that ships no Python package — a straightforwardly wrong change that somebody would have to review and reject.

One question, @bamr87:

Given claude-release.yml already covers this and GitHubAI ships no Python package, what should happen to #69?

• Option A — close as substantially delivered, and open a small follow-up for the one real gap (recommended). The follow-up is narrow and unambiguous: add a guarded push: branches: [main] trigger to prepare mode, plus reconcile the missing CHANGELOG.md. I would hand that straight to tier 2. The premise-broken criteria (PyPI, auto-tagging) simply go away with the ticket rather than lingering as apparent scope.
• Option B — keep [Feature Request]: Automated Python Package Versioning in CI/CD #69 open, narrowed in place. I have already rewritten the body to score every original criterion against today's main, so it is accurate as a narrowed ticket. Re-label it agent:ready and tier 2 implements the trigger only. Costs nothing but leaves a 495-day-old ticket alive for a one-line change.
• Option C — migrate to the fleet's release-please standard instead. Replace the bespoke claude-release.yml with tools/adopt-release.sh + bamr87/.github's reusable release-please.yml, as zer0-image-generator runs successfully today. That would make versioning fully conventional-commit-driven and align githubai with the rest of the fleet — but it is a real architectural change, it discards a working Claude-native workflow you built deliberately, and it interacts with chore(deps-dev): bump vite and @vitejs/plugin-react in /frontend #97 in the hub. Much larger than this ticket.

My recommendation: Option A. The issue has served its purpose; the code caught up with it.

Whichever you pick, one thing should change regardless: the title claims "Python Package Versioning", which this repo does not do. That phrasing is what makes the ticket read as unfinished when it mostly is not.