Release

Release Agent Lightning

Merging a pull request does not publish a stable release. Stable publication is triggered only by pushing a v* tag to the canonical repository; the tagged commit is what gets tested, built, and uploaded. That same tag push also deploys versioned documentation and moves the public stable alias, so a release has two public side effects, not one.

Establish the release state

1. Confirm the repository root, clean working tree, current branch, and remotes.
2. Resolve the canonical OWNER/REPO, its default branch, and its permitted merge methods with gh repo view OWNER/REPO --json nameWithOwner,defaultBranchRef,mergeCommitAllowed,rebaseMergeAllowed,squashMergeAllowed. Identify the local remotes for that repository and the contributor fork by their URLs; do not assume particular remote names or merge settings.
3. Inspect the release contract in:
   • .github/workflows/pypi-release.yml
   • .github/workflows/docs.yml
   • .github/workflows/tests.yml
   • scripts/bump_version.sh
   • pyproject.toml
   • agentlightning/__init__.py
4. Confirm the canonical default branch is already green before branching from it. Resolve its current commit with gh api repos/OWNER/REPO/commits/<default-branch> and inspect that commit's check runs; a general recent-run listing can omit or mix commits. A release branch inherits every failure that main is carrying.
5. Query the canonical repository's tags and compare them with the versions published at https://pypi.org/pypi/agentlightning/json. Confirm the target version exists in neither place, and stop for an explicit release decision when either of these holds:
   • A tag exists with no matching PyPI version. A published version is immutable, and its tag must never be reused or moved. A tag that never published is a different situation and still needs a human decision, informed by why it did not publish. See "Recovering a tag that never published" below.
   • The proposed bump would skip a version that was tagged but never published.
6. Treat verified PyPI trusted-publisher configuration for the canonical repository and pypi-release.yml as a prerequisite. If it cannot be inspected directly, require confirmation from an authorized PyPI project owner before pushing the release tag.

Prepare and merge the version pull request

Start a release branch from a freshly fetched canonical default branch, not from another feature branch. The branch name is only a recommendation:

git fetch <canonical-remote> <default-branch>
git switch -c chore/release-vX.Y.Z <canonical-remote>/<default-branch>
scripts/bump_version.sh patch  # or minor / major

The script updates the project version with uv and then edits agentlightning/__init__.py separately. If it fails or is interrupted between those writes, only some of the three version files may be updated. Inspect git diff after any failure and restore or reconcile all three files before retrying; blindly rerunning a partial patch bump can advance the version twice.

The bump rewrites exactly three files. Confirm that with git diff --stat:

• pyproject.toml
• the agentlightning entry in uv.lock
• agentlightning.__version__ in agentlightning/__init__.py

Other version strings in the tree, such as the FastAPI version in agentlightning/server/app.py, are deliberately outside the bump. Leave them alone; changing them is a separate pull request, not release work.

Review the version diff, but do not run the release tests or package build locally as a matter of course. tests.yml runs a broader test suite and the same package build on the pull request, covering the narrower tests and build that pypi-release.yml will run on the tag. The pull request's GitHub checks are therefore the verification gate. Reproduce a single failure locally only when the workflow logs are not enough to fix it.

Commit the version change, push it to the fork, and open the pull request with the GitHub CLI when those external actions are authorized:

git commit -am "Bump version to X.Y.Z"
git push -u <fork-remote> <release-branch>
gh pr create --repo OWNER/REPO \
  --base <default-branch> \
  --head <fork-owner>:<release-branch> \
  --title "Bump version to X.Y.Z" \
  --body "Prepare the vX.Y.Z release."

gh pr create refuses to run without --title and --body outside an interactive terminal, and every gh call needs --repo OWNER/REPO so it acts on the canonical repository rather than the fork.

Follow the pull request through its required checks with gh pr checks <pr> --repo OWNER/REPO --watch. If a check fails, take the run id from that output, inspect it with gh run view <run-id> --repo OWNER/REPO --log-failed, correct the source on the same branch, and resume watching. Once every required check has succeeded, extract the reviewed head and pass both a permitted merge-method flag from step 2 and --match-head-commit to gh pr merge:

HEAD_SHA="$(gh pr view <pr> --repo OWNER/REPO --json headRefOid --jq .headRefOid)"
gh pr merge <pr> --repo OWNER/REPO <merge-method-flag> \
  --match-head-commit "$HEAD_SHA"

Replace <merge-method-flag> with one permitted flag discovered in step 2: --merge, --rebase, or --squash.

Committing, pushing, opening the pull request, and merging are each distinct external actions and each requires authorization.

Tag and publish the merged release

After the pull request merges, update the local default branch from the canonical repository, then confirm that the commit you are about to tag is the one this pull request produced and not a later commit that landed behind it:

git switch <default-branch>
git pull --ff-only <canonical-remote> <default-branch>
gh pr view <pr> --repo OWNER/REPO --json mergeCommit
git rev-parse HEAD

If HEAD has moved past the merge commit, tag the merge commit explicitly instead of HEAD.

pypi-release.yml fails the release when the packaged version does not equal the tag without its leading v, or when it does not equal the runtime __version__. Check both before tagging:

uv version --short
grep '^__version__' agentlightning/__init__.py

The workflow itself reads the runtime value as python -c 'from agentlightning import __version__; print(__version__)' from the repository root before its dependency-sync step, so Python resolves the checkout through the current working directory. Read the file directly for the local pre-tag check; agentlightning/__init__.py assigns __version__ as a single literal, making that check independent of the active Python environment.

GitHub reads workflow files as they exist at the tagged commit, not at the tip of the default branch. Confirm that the commit being tagged actually contains .github/workflows/pypi-release.yml with its v* trigger; a commit that predates the workflow will never publish, however the tag is pushed.

Immediately query the canonical repository and PyPI again to ensure that vX.Y.Z is still absent. Then create an annotated tag on the release commit and push it to the canonical repository:

git tag -a vX.Y.Z -m "vX.Y.Z" <release-commit>
git push <canonical-remote> vX.Y.Z

The tag push starts the production PyPI publication, so obtain explicit authorization immediately before it.