Docs: Check and Deploy workflow (geometric-intelligence/topobench)

The Docs: Check and Deploy workflow from geometric-intelligence/topobench, 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.

Grade your own workflow free or run it on Latchkey →

Source: geometric-intelligence/topobench.github/workflows/docs.ymlLicense MITView source

What it does

This is the Docs: Check and Deploy workflow from the geometric-intelligence/topobench 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

workflow (.yml)

name: "Docs: Check and Deploy"

on:
  push:
    branches: [main, github-actions-test]
  pull_request:
    branches: [main]
  workflow_dispatch:

# Project site https://geometric-intelligence.github.io/topobench/ is published from
# this repo's gh-pages branch - not from geometric-intelligence.github.io/topobench/.
concurrency:
  group: topobench-docs-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

permissions:
  contents: write

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11"]

    steps:
      - uses: actions/checkout@v4

      # 1. Setup uv
      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          python-version: ${{ matrix.python-version }}
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      # 2. Run your centralized installation script
      - name: Install dependencies (via script)
        run: |
          # This installs '.[all]' which includes doc dependencies
          source uv_env_setup.sh

      # 3. Install System Dependencies
      - name: Install Pandoc
        run: sudo apt-get -y install pandoc

      # 4. Generate Docs
      - name: Generate API Documentation
        run: |
          source .venv/bin/activate
          cd docs
          bash generate_api_docs.sh

      - name: Generate Docs [Sphinx]
        run: |
          source .venv/bin/activate
          sphinx-build -b html -D version=latest -D release=latest docs docs/_build
          # Disable Jekyll so paths like _static/ are served as static files.
          touch docs/_build/.nojekyll

      # 5. Deploy - same repo gh-pages powers https://geometric-intelligence.github.io/topobench/
      - name: Deploy Docs
        uses: JamesIves/github-pages-deploy-action@v4
        if: ${{ github.ref == 'refs/heads/main' && github.repository == 'geometric-intelligence/topobench' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
        with:
          branch: gh-pages
          folder: docs/_build
          token: ${{ secrets.GITHUB_TOKEN }}
          clean: true

The same workflow, on Latchkey

Removes redundant runs and caps runaway jobs. Added and changed lines are highlighted.

name: "Docs: Check and Deploy"
 
on:
  push:
    branches: [main, github-actions-test]
  pull_request:
    branches: [main]
  workflow_dispatch:
 
# Project site https://geometric-intelligence.github.io/topobench/ is published from
# this repo's gh-pages branch - not from geometric-intelligence.github.io/topobench/.
concurrency:
  group: topobench-docs-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false
 
permissions:
  contents: write
 
jobs:
  build:
    timeout-minutes: 30
    runs-on: latchkey-small
    strategy:
      matrix:
        python-version: ["3.11"]
 
    steps:
      - uses: actions/checkout@v4
 
      # 1. Setup uv
      - name: Install uv
        uses: astral-sh/setup-uv@v5
        with:
          python-version: ${{ matrix.python-version }}
          enable-cache: true
          cache-dependency-glob: "uv.lock"
 
      # 2. Run your centralized installation script
      - name: Install dependencies (via script)
        run: |
          # This installs '.[all]' which includes doc dependencies
          source uv_env_setup.sh
 
      # 3. Install System Dependencies
      - name: Install Pandoc
        run: sudo apt-get -y install pandoc
 
      # 4. Generate Docs
      - name: Generate API Documentation
        run: |
          source .venv/bin/activate
          cd docs
          bash generate_api_docs.sh
 
      - name: Generate Docs [Sphinx]
        run: |
          source .venv/bin/activate
          sphinx-build -b html -D version=latest -D release=latest docs docs/_build
          # Disable Jekyll so paths like _static/ are served as static files.
          touch docs/_build/.nojekyll
 
      # 5. Deploy - same repo gh-pages powers https://geometric-intelligence.github.io/topobench/
      - name: Deploy Docs
        uses: JamesIves/github-pages-deploy-action@v4
        if: ${{ github.ref == 'refs/heads/main' && github.repository == 'geometric-intelligence/topobench' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
        with:
          branch: gh-pages
          folder: docs/_build
          token: ${{ secrets.GITHUB_TOKEN }}
          clean: true

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 uses latchkey-small; pick the runner size that fits the job.
Add a job timeout so a hung step cannot burn hours of runner time.

2 third-party actions are referenced by a movable tag. Pin them to the commit SHA (Latchkey resolves and applies this automatically) so a repointed tag cannot change what runs.

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.

Actions used in this workflow

actions/checkout astral-sh/setup-uv