Release Process¶
Documentation Deployment¶
.github/workflows/docs.yml builds the site strictly on pull requests and pushes to main. Successful main-branch builds commit generated HTML to the separate gh-pages branch. The same generated site is uploaded with GitHub’s Pages artifact action and deployed at https://colinconwell.github.io/Aesop-Agentic/.
This follows the Material for MkDocs branch deployment pattern. Source Markdown remains on main; generated site/ files are ignored locally. Configure Pages to use GitHub Actions. The workflow retains the separate gh-pages snapshot and deploys those same built files explicitly because commits made with GITHUB_TOKEN do not trigger another Pages build. The workflow also supports manual dispatch. The github.io URL inherits the account’s existing custom domain and redirects to https://colinconwell.com/Aesop-Agentic/.
Package Validation and Publication¶
.github/workflows/publish.yml tests the package, builds a wheel and source distribution, checks metadata, installs the wheel outside the checkout, and validates packaged resources. Pull requests, main-branch pushes, and manual dispatch validate without uploading. Publishing a GitHub release with a v<version> tag enables the separate PyPI upload job after validation.
The release tag must match pyproject.toml and aesop_agentic.__version__. The PyPI artifacts contain the Python package and browser assets. Native Tauri releases are a separate build/distribution step.
Configure PyPI Trusted Publishing with:
| Field | Value |
|---|---|
| PyPI Project | aesop-agentic |
| Repository Owner | ColinConwell |
| Repository | Aesop-Agentic |
| Workflow | publish.yml |
| Environment | pypi |
For a project without an uploaded release, use PyPI's pending-publisher setup. GitHub's pypi environment supplies the matching identity; the upload job alone receives id-token: write. No long-lived PyPI API token is required.
Test Workflows Locally¶
Install nektos/act and start Docker. From the checkout:
act push -W .github/workflows/docs.yml -P ubuntu-latest=catthehacker/ubuntu:act-latest --container-architecture linux/amd64
act push -W .github/workflows/publish.yml -j build -P ubuntu-latest=catthehacker/ubuntu:act-latest --container-architecture linux/amd64
The source repository is private; PyPI distributions and the Pages site are public. For local Actions checkout, pass a GitHub token using -s GITHUB_TOKEN or an ignored secret file. Do not commit tokens. act exercises Linux build and validation steps. Deployment, artifact upload, and PyPI upload are gated off under act; GitHub OIDC and hosted macOS runners require an official Actions run.
After local validation, push to GitHub, inspect the official workflows, and publish the versioned GitHub release. Verify the resulting PyPI files with a fresh install from the index and open the public Pages URL. PyPI versions cannot be overwritten: fix a published defect with a new version.