Release and Pages automation¶

This page documents the release and documentation deployment parts of dpone CI/CD. For the complete release checklist, see Release.

Release path¶

sequenceDiagram
    participant Dev as Maintainer
    participant Git as GitHub master
    participant GHA as GitHub Actions release.yml
    participant PyPI as PyPI dpone

    Dev->>Git: Push annotated tag vX.Y.Z
    Git->>GHA: Trigger Release workflow
    GHA->>GHA: uv sync --all-extras
    GHA->>GHA: uv build
    GHA->>GHA: twine check dist/*
    GHA->>PyPI: Publish via Trusted Publishing
    PyPI-->>GHA: Release accepted

Trusted Publishing¶

Preferred PyPI publishing mode is Trusted Publishing through GitHub OIDC.

Expected PyPI Pending Publisher settings:

Field	Value
Project	`dpone`
Owner	`PaulKov`
Repository	`dpone`
Workflow filename	`release.yml`
Environment	`pypi`

The GitHub workflow uses environment pypi and id-token: write permission for the publish job.

Token fallback¶

Manual token fallback exists only for emergencies:

Workflow input: use_pypi_token=true.
GitHub secret: PYPI_API_TOKEN.
Scope: package-specific PyPI token when possible.

After fallback use, rotate the token. Never use a token that has been pasted into chat, an issue, a PR, or logs.

Release checklist¶

Before tagging:

uv sync --all-extras
uv run ruff check .
uv run ruff format --check .
uv run mypy --config-file mypy.ini
uv run pytest -m "not integration_live" --cov=src/dpone --cov-report=xml
uv build
uv tool run twine check dist/*

Then:

git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

After publishing:

python -m venv /tmp/dpone-release-smoke
/tmp/dpone-release-smoke/bin/pip install -U pip
/tmp/dpone-release-smoke/bin/pip install dpone==X.Y.Z
/tmp/dpone-release-smoke/bin/dpone --help

GitHub Pages path¶

flowchart LR
    DocsChange["docs/** or mkdocs.yml change"] --> Build["mkdocs build --strict"]
    Build --> Artifact["Upload Pages artifact"]
    Artifact --> Deploy["Deploy GitHub Pages"]
    Deploy --> Site["paulkov.github.io/dpone"]

The docs workflow:

builds on pull requests but does not deploy;
builds and deploys on push to master;
can be started manually;
deploys through GitHub Actions Pages source.

Local preview:

python -m pip install -r docs/requirements.txt
mkdocs serve

Production build:

mkdocs build --strict

Pages runbook shortcuts¶

If the site is stale:

Check the latest docs workflow run on master.
Check repository Settings -> Pages and confirm the source is GitHub Actions.
Confirm the changed page is reachable from MkDocs nav or from an indexed docs page.

If Mermaid renders as code:

Confirm mkdocs.yml has pymdownx.superfences with a mermaid custom fence.
Confirm the diagram block starts with ```mermaid.
Run mkdocs build --strict and inspect generated HTML for class="mermaid".