Generate and deploy API documentation workflow (Donkie/Spoolman)
The Generate and deploy API documentation workflow from Donkie/Spoolman, explained and optimized by Latchkey.
CI health: C - fair
Point runs-on at Latchkey and get caching, job timeouts, SHA-pinned actions, self-healing for flaky steps, and up to 58% lower cost, applied automatically.
What it does
This is the Generate and deploy API documentation workflow from the Donkie/Spoolman repository, a real project running GitHub Actions. It is shown here with attribution under its MIT license.
Below, Latchkey shows a faster, safer version produced by its optimization engine.
The workflow
name: Generate and deploy API documentation
on:
release:
types: [published]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Install uv
uses: astral-sh/setup-uv@v7
with:
version: "0.9.26"
- name: "Set up Python"
uses: actions/setup-python@v6
with:
python-version-file: "pyproject.toml"
- name: Install Poe the Poet
run: uv tool install poethepoet
- run: uv sync
- run: poe generate-docs
- name: Setup Pages
uses: actions/configure-pages@v5.0.0
- name: Upload artifact
uses: actions/upload-pages-artifact@v3.0.1
with:
path: "docs/"
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4.0.5
The same workflow, on Latchkey
Estimated ~20% faster on cache hits, plus fewer wasted runs and a safer supply chain. Added and changed lines are highlighted.
name: Generate and deploy API documentation on: release: types: [published] workflow_dispatch: permissions: contents: read pages: write id-token: write # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. concurrency: group: "pages" cancel-in-progress: false jobs: # Single deploy job since we're just deploying deploy: timeout-minutes: 30 environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} runs-on: latchkey-small steps: - name: Checkout uses: actions/checkout@v6 - name: Install uv uses: astral-sh/setup-uv@v7 with: version: "0.9.26" - name: "Set up Python" uses: actions/setup-python@v6 with: cache: 'pip' python-version-file: "pyproject.toml" - name: Install Poe the Poet run: uv tool install poethepoet - run: uv sync - run: poe generate-docs - name: Setup Pages uses: actions/configure-pages@v5.0.0 - name: Upload artifact uses: actions/upload-pages-artifact@v3.0.1 with: path: "docs/" - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4.0.5
What changed
- Run on Latchkey managed runners with one line (
runs-on), which apply the fixes below automatically and self-heal transient failures. This example useslatchkey-small; pick the runner size that fits the job. - Cache dependency installs on the setup step so they are served from cache.
- Add a job timeout so a hung step cannot burn hours of runner time.
1 third-party action is referenced by a movable tag. Pin it to the commit SHA (Latchkey resolves and applies this automatically) so a repointed tag cannot change what runs.
This workflow runs 1 job per trigger. On Latchkey the same minutes cost up to 58% less than GitHub-hosted, with zero queue time.