Stack CLI Release Process

Stack CLI Release Process

Overview

The sscli package is published to PyPI via GitHub Actions when a Git tag is pushed to the repository. The workflow is defined in .github/workflows/publish-pip.yml and is triggered only on tags matching the pattern v*.*.* (e.g., v2.0.3).

Prerequisites

• ✅ All code changes committed to main in both foundry-meta and tooling/stack-cli submodule
• ✅ Version bumped in tooling/stack-cli/pyproject.toml
• ✅ All related submodules updated in foundry-meta

Release Steps

1. Create a Git Tag (CRITICAL STEP)

The workflow only triggers when a tag is pushed. Without this step, the CI will NOT run.

# Navigate to foundry-meta repo
cd <foundry-meta-root>

# Create an annotated tag (required by GitHub Actions)
git tag -a v2.0.3 -m "Release sscli v2.0.3: Default interactive mode, enhanced UI"

# Push the tag to trigger the workflow
git push origin v2.0.3

2. Verify the Workflow Runs

• Go to GitHub Actions
• Look for “Publish sscli to PyPI” workflow
• It should start running within a few seconds
• Check logs for any failures

3. Verify PyPI Package

After workflow succeeds, verify the package is available:

# Check PyPI
python -m pip index versions sscli

# Install the new version
pip install sscli==2.0.3

Common Issues & Solutions

Problem: Workflow Didn’t Run After Pushing Commits

Root Cause: No tag was created. The workflow triggers only on tag push, not regular commits.

Solution:

git tag -a v2.0.3 -m "Release message"
git push origin v2.0.3

Problem: Changes Not Visible in Local Testing

Root Cause: After modifying code in tooling/stack-cli, the installed package isn’t updated.

Solution: Rebuild/reinstall the dev package:

# If using sscli-dev swap
rm -rf /path/to/sscli-dev/build /path/to/sscli-dev/dist
python -m build  # Rebuild the dist/

# Or reinstall from source
cd tooling/stack-cli
pip install -e .  # Development mode install (if supported)
# OR
pip install --force-reinstall .  # Force reinstall

Problem: Version in Tag Doesn’t Match pyproject.toml

Solution: Ensure they match exactly:

• Tag: v2.0.3
• File: tooling/stack-cli/pyproject.toml → version = "2.0.3"

The GitHub Actions workflow will update this automatically if needed, but consistency is important.

Workflow Details

The publish-pip.yml workflow:

1. Trigger: Tag push matching v*.*.*
2. Parse Version: Extracts version from tag (e.g., v2.0.3 → 2.0.3)
3. Update pyproject.toml: Sets version in the file to match tag (automation safety check)
4. Build Package: Creates distribution files (wheel, sdist)
5. Upload to PyPI: Uses ${{ secrets.PYPI_API_TOKEN }} to publish
6. Create GitHub Release: Creates a release entry with built artifacts

Environment Variables & Secrets

The workflow uses:

• ${{ secrets.PYPI_API_TOKEN }}: Required to publish to PyPI
• ${{ secrets.GH_PAT }}: GitHub Personal Access Token (optional fallback for checkouts)

These must be configured in repository settings.

Quick Checklist for Release

• Code changes committed to main in both repos
• Version bumped in tooling/stack-cli/pyproject.toml
• All submodule pointers updated in foundry-meta
• Create annotated tag: git tag -a v2.0.X -m "message"
• Push tag: git push origin v2.0.X
• Wait for GitHub Actions to complete
• Verify package on PyPI
• Test installation: pip install sscli==2.0.X

For AI Agents

CRITICAL: Every time you:

1. Bump the version, remind user to create a tag before push
2. Complete release work, provide the exact git tag and git push commands
3. Note in commits: Reference the tag pattern (feat|fix|chore): msg without auto-tagging

The tag creation is a MANUAL STEP that must happen AFTER commits are pushed to main.