Update stable docs branch workflow (ddev/ddev)

The Update stable docs branch workflow from ddev/ddev, explained and optimized by Latchkey.

CI health: A - excellent

Point runs-on at Latchkey and get job timeouts, self-healing for flaky steps, and up to 58% lower cost, applied automatically.

Grade your own workflow free or run it on Latchkey →

Source: ddev/ddev.github/workflows/docs-stable.ymlLicense Apache-2.0View source

What it does

This is the Update stable docs branch workflow from the ddev/ddev repository, a real project running GitHub Actions. It is shown here with attribution under its Apache-2.0 license.

Below, Latchkey shows a faster, safer version produced by its optimization engine.

The workflow

workflow (.yml)

name: Update stable docs branch

# Approach based on https://til.simonwillison.net/readthedocs/stable-docs
#
# On release published: reset the stable branch to the tagged commit so
# ReadTheDocs rebuilds /stable/ from the new release.
# To push doc fixes without a release, commit directly to the stable branch.
#
# More details in https://docs.ddev.com/en/stable/developers/testing-docs/#updating-stable-docs-without-a-release

on:
  release:
    types: [published]

permissions:
  contents: write

jobs:
  update-stable-branch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Configure git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Create stable branch if it does not yet exist
        run: |
          if ! git ls-remote --heads origin stable | grep -q stable; then
            git checkout -b stable
            LATEST_RELEASE=$(git tag | sort -Vr | head -n1)
            if [ -n "$LATEST_RELEASE" ]; then
              rm -rf docs/
              git checkout "$LATEST_RELEASE" -- docs/
            fi
            git commit -m "docs: populate from $LATEST_RELEASE" || echo "No changes"
            git push -u origin stable
          fi

      - name: Reset stable to release tag
        if: github.event_name == 'release' && !github.event.release.prerelease
        run: |
          git fetch --all
          git checkout stable
          git reset --hard "${GITHUB_REF#refs/tags/}"
          git push origin stable --force

The same workflow, on Latchkey

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

name: Update stable docs branch
 
# Approach based on https://til.simonwillison.net/readthedocs/stable-docs
#
# On release published: reset the stable branch to the tagged commit so
# ReadTheDocs rebuilds /stable/ from the new release.
# To push doc fixes without a release, commit directly to the stable branch.
#
# More details in https://docs.ddev.com/en/stable/developers/testing-docs/#updating-stable-docs-without-a-release
 
on:
  release:
    types: [published]
 
permissions:
  contents: write
 
jobs:
  update-stable-branch:
    timeout-minutes: 30
    runs-on: latchkey-small
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
 
      - name: Configure git
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
 
      - name: Create stable branch if it does not yet exist
        run: |
          if ! git ls-remote --heads origin stable | grep -q stable; then
            git checkout -b stable
            LATEST_RELEASE=$(git tag | sort -Vr | head -n1)
            if [ -n "$LATEST_RELEASE" ]; then
              rm -rf docs/
              git checkout "$LATEST_RELEASE" -- docs/
            fi
            git commit -m "docs: populate from $LATEST_RELEASE" || echo "No changes"
            git push -u origin stable
          fi
 
      - name: Reset stable to release tag
        if: github.event_name == 'release' && !github.event.release.prerelease
        run: |
          git fetch --all
          git checkout stable
          git reset --hard "${GITHUB_REF#refs/tags/}"
          git push origin stable --force

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.

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