Docs workflow (personalrobotics/ssik)
The Docs workflow from personalrobotics/ssik, explained and optimized by Latchkey.
CI health: B - good
Point runs-on at Latchkey and get job timeouts, SHA-pinned actions, self-healing for flaky steps, and up to 58% lower cost, applied automatically.
What it does
This is the Docs workflow from the personalrobotics/ssik 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: Docs
# Build + deploy mkdocs-material site to GitHub Pages on push to main.
# The site lives at https://personalrobotics.github.io/ssik/.
#
# Pre-#266 docs were the in-repo docs/*.md only. The mkdocs site adds:
# - auto-generated API reference from docstrings via mkdocstrings[python]
# - getting-started + setting-up-your-robot narrative pages
# - long-form solver specs from docs/specs/
on:
push:
branches: [main]
paths:
- "mkdocs.yml"
- "docs/**"
- "src/ssik/**" # API reference is auto-generated from docstrings
- ".github/workflows/docs.yml"
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # hatch-vcs needs git history
- name: Set up uv
uses: astral-sh/setup-uv@v4
with:
enable-cache: true
cache-dependency-glob: "uv.lock"
- name: Install docs dependency group
run: uv sync --group docs
- name: Build mkdocs site
run: uv run mkdocs build --strict
- uses: actions/upload-pages-artifact@v3
with:
path: site
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v4
The same workflow, on Latchkey
Removes redundant runs and caps runaway jobs. Added and changed lines are highlighted.
name: Docs # Build + deploy mkdocs-material site to GitHub Pages on push to main. # The site lives at https://personalrobotics.github.io/ssik/. # # Pre-#266 docs were the in-repo docs/*.md only. The mkdocs site adds: # - auto-generated API reference from docstrings via mkdocstrings[python] # - getting-started + setting-up-your-robot narrative pages # - long-form solver specs from docs/specs/ on: push: branches: [main] paths: - "mkdocs.yml" - "docs/**" - "src/ssik/**" # API reference is auto-generated from docstrings - ".github/workflows/docs.yml" workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false jobs: build: timeout-minutes: 30 runs-on: latchkey-small steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # hatch-vcs needs git history - name: Set up uv uses: astral-sh/setup-uv@v4 with: enable-cache: true cache-dependency-glob: "uv.lock" - name: Install docs dependency group run: uv sync --group docs - name: Build mkdocs site run: uv run mkdocs build --strict - uses: actions/upload-pages-artifact@v3 with: path: site deploy: timeout-minutes: 30 needs: build runs-on: latchkey-small environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - id: deployment uses: actions/deploy-pages@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. - 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 2 jobs per trigger. On Latchkey the same minutes cost up to 58% less than GitHub-hosted, with zero queue time.