Generate API Documentation workflow (SpecterOps/Nemesis)
The Generate API Documentation workflow from SpecterOps/Nemesis, explained and optimized by Latchkey.
CI health: C - fair
Point runs-on at Latchkey and get run de-duplication, job timeouts, self-healing for flaky steps, and up to 58% lower cost, applied automatically.
What it does
This is the Generate API Documentation workflow from the SpecterOps/Nemesis repository, a real project running GitHub Actions. It is shown here with attribution under its BSD-3-Clause license.
Below, Latchkey shows a faster, safer version produced by its optimization engine.
The workflow
name: Generate API Documentation
on:
push:
branches: [main]
paths:
- 'projects/web_api/**'
- '.github/workflows/generate-api-docs.yml'
- '.github/scripts/generate_api_docs.py'
workflow_dispatch: # For manual triggering
jobs:
generate-docs:
runs-on: ubuntu-22.04
permissions:
contents: write
pages: write
id-token: write
environment:
name: github-pages
steps:
- name: Checkout repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
with:
fetch-depth: 0
- name: Install uv
uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
- name: Setup Python 3.12
run: uv python install 3.12
- name: Install dependencies
run: |
cd projects/web_api
uv sync --frozen
- name: Generate API documentation
run: |
cd projects/web_api
uv run python ../../.github/scripts/generate_api_docs.py
- name: Commit documentation changes
uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7
with:
commit_message: 'docs: update API documentation [skip ci]'
file_pattern: 'docs/*'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Install mkdocs dependencies
run: |
uv venv
uv pip install -r docs/requirements.txt
- name: Build documentation
run: |
uv run mkdocs build
- name: Setup Github pages
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
- name: Create Github pages artifact
uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
with:
path: site
- name: Deploy documentation to Github pages
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
The same workflow, on Latchkey
Removes redundant runs and caps runaway jobs. Added and changed lines are highlighted.
name: Generate API Documentation on: push: branches: [main] paths: - 'projects/web_api/**' - '.github/workflows/generate-api-docs.yml' - '.github/scripts/generate_api_docs.py' workflow_dispatch: # For manual triggering concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true jobs: generate-docs: timeout-minutes: 30 runs-on: latchkey-small permissions: contents: write pages: write id-token: write environment: name: github-pages steps: - name: Checkout repository uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 with: fetch-depth: 0 - name: Install uv uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7 - name: Setup Python 3.12 run: uv python install 3.12 - name: Install dependencies run: | cd projects/web_api uv sync --frozen - name: Generate API documentation run: | cd projects/web_api uv run python ../../.github/scripts/generate_api_docs.py - name: Commit documentation changes uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7 with: commit_message: 'docs: update API documentation [skip ci]' file_pattern: 'docs/*' env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Install mkdocs dependencies run: | uv venv uv pip install -r docs/requirements.txt - name: Build documentation run: | uv run mkdocs build - name: Setup Github pages uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5 - name: Create Github pages artifact uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4 with: path: site - name: Deploy documentation to Github pages uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
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. - Cancel superseded runs when a branch or PR gets a newer push.
- Add a job timeout so a hung step cannot burn hours of runner time.
What Latchkey heals here
This workflow has steps that commonly fail on transient issues (network, registries, flaky browsers). On Latchkey managed runners they are detected, retried, and self-healed instead of failing your build:
- Dependency installs
This workflow runs 1 job per trigger. On Latchkey the same minutes cost up to 58% less than GitHub-hosted, with zero queue time.