Release Process

Relevant source files

• .github/dependabot.yaml
• .github/workflows/nix-flake-update.yaml
• .github/workflows/nix-flake.yaml
• .github/workflows/release.yaml
• .release-please-manifest.json
• CHANGELOG.md

This document describes the automated release workflow for the StackOne AI Python SDK. The release process uses release-please to implement semantic versioning based on conventional commits, automatically generating changelogs, updating version numbers, and publishing packages to PyPI.

For detailed configuration of the release-please system, see Release Please Configuration. For the complete release workflow implementation, see Release Workflow. For general CI/CD pipeline information, see CI/CD Pipeline.

Overview

The StackOne AI SDK employs a fully automated, zero-touch release process. Releases are triggered by conventional commits to the main branch, which release-please analyzes to determine version bumps and generate release artifacts. The system automatically updates the Python lock file (uv.lock) as part of release pull requests and publishes packages to PyPI upon release creation.

Release Workflow Architecture

Sources: .github/workflows/release.yaml1-67 .release-please-manifest.json1-4

Release Triggering Mechanism

Releases are triggered automatically when commits following the Conventional Commits specification are pushed to the main branch. The release-please-action analyzes commit messages to determine the next version number according to semantic versioning rules.

Commit Type to Version Bump Mapping

Commit Type	Version Impact	Example	Resulting Version Change
feat:	Minor version	feat: add semantic search	2.3.0 → 2.4.0
fix:	Patch version	fix: parameter validation	2.3.0 → 2.3.1
BREAKING CHANGE:	Major version	feat!: remove deprecated API	2.3.0 → 3.0.0
chore:, docs:, refactor:	No release	chore: update deps	No version change

The workflow runs on every push to main but only creates release PRs or releases when relevant commits are detected:

Sources: .github/workflows/release.yaml3-6 CHANGELOG.md1-187

Release Pipeline Phases

The release workflow operates in two distinct phases: the Release PR Phase and the Release Creation Phase. These phases are controlled by output conditionals from the release-please-action.

Release Phases Flow Diagram

Sources: .github/workflows/release.yaml13-67

Phase 1: Release PR Management

When release-please detects conventional commits, it creates or updates a release pull request. This PR contains:

1. Version number updates in pyproject.toml
2. Changelog generation in CHANGELOG.md with grouped commits
3. Manifest updates in .release-please-manifest.json

The workflow then performs an additional automation step specific to Python projects:

This ensures that uv.lock reflects the new version specified in pyproject.toml, maintaining lock file consistency across the release.

Sources: .github/workflows/release.yaml22-47

Phase 2: Package Publication

When a release PR is merged, release-please detects the merge and triggers the publication phase:

This phase:

1. Creates a GitHub release with auto-generated release notes
2. Creates a git tag matching the version (e.g., stackone-ai-v2.4.0)
3. Builds the package using uv build (invoked via just build)
4. Publishes to PyPI using uv publish with the PYPI_API_TOKEN secret

Sources: .github/workflows/release.yaml49-67

Version Management Strategy

The project uses a single-package monorepo structure with version tracking in .release-please-manifest.json:

The "." key indicates the root package. The version number follows semantic versioning (MAJOR.MINOR.PATCH) and is synchronized across multiple files during release:

Version Synchronization Points

Sources: .release-please-manifest.json1-4 CHANGELOG.md1-10

Release Workflow Permissions

The release workflow requires elevated permissions to create releases and update pull requests:

These permissions allow the workflow to:

• Create and update release pull requests
• Push commits to release PR branches (for uv.lock updates)
• Create GitHub releases and git tags
• Publish changelog updates

Sources: .github/workflows/release.yaml8-10

Integration with Dependency Management

The release process integrates with the broader dependency management ecosystem documented in Dependency Management:

Release and Dependency Update Coordination

Update Type	Frequency	Mechanism	Interaction with Releases
Release-triggered uv.lock	Per release	Automatic in release PR	Synchronized with version bump
Python dependencies	Weekly (Monday 09:00)	Dependabot PR	Independent, merged before releases
Nix flake inputs	Weekly (Monday 09:00)	nix-flake-update workflow	Independent, auto-merged
GitHub Actions	Weekly (Monday 09:00)	Dependabot PR	Independent, merged before releases

The release workflow deliberately uses skip-uv-sync: "true" in the setup-nix action because it explicitly manages uv.lock as part of the release process:

This prevents double synchronization and ensures the workflow has full control over when and how uv.lock is updated during releases.

Sources: .github/workflows/release.yaml29-33 .github/dependabot.yaml1-47 .github/workflows/nix-flake-update.yaml1-64

Release Artifacts

Each successful release produces the following artifacts:

1. GitHub Release: Created automatically with release notes derived from conventional commits
2. Git Tag: Format stackone-ai-vX.Y.Z (e.g., stackone-ai-v2.4.0)
3. PyPI Package: Published as both source distribution (.tar.gz) and wheel (.whl)
4. Updated CHANGELOG.md: Grouped commits by type with links to PRs and commits
5. Updated uv.lock: Synchronized with the new version

Changelog Structure Example

The generated changelog groups commits by conventional type:

Each entry includes:

• Commit scope (e.g., search:, ci:)
• Commit message
• Pull request reference with link
• Commit SHA with link

Sources: CHANGELOG.md1-30

Manual Release Trigger

While releases are normally automatic, maintainers can manually trigger a release by:

1. Creating a commit with the conventional commit format
2. Adding the magic string Release-As: X.Y.Z in the commit body

Example:

This bypasses the automatic version calculation and forces a specific version number.

Sources: .github/workflows/release.yaml1-67

Failure Handling

The release workflow includes several safeguards:

1. Conditional execution: Each phase only runs if the appropriate output is set (pr or release_created)
2. Lock file check: The uv lock update only commits if changes are detected
3. Separate checkout steps: PR updates and releases use independent checkout operations
4. Token isolation: PyPI publishing uses a dedicated secret (PYPI_API_TOKEN)

If the release workflow fails:

• Release PRs remain open and can be manually merged after fixing issues
• Failed PyPI publishes do not affect GitHub release creation (they occur after)
• The workflow can be re-triggered by pushing a new commit to main

Sources: .github/workflows/release.yaml13-67