Documentation workflow (Automattic/mongoose)
The Documentation workflow from Automattic/mongoose, explained and optimized by Latchkey.
D
CI health: D - needs work
Point runs-on at Latchkey and get caching, run de-duplication, job timeouts, self-healing for flaky steps, and up to 58% lower cost, applied automatically.
What it does
This is the Documentation workflow from the Automattic/mongoose 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: Documentation
on:
pull_request:
paths:
- '.github/workflows/documentation.yml'
- 'package.json'
- 'docs/**'
- 'lib'
- 'test'
- 'scripts/website.js'
- 'CHANGELOG.md'
- 'CONTRIBUTING.md'
- 'index.pug'
push:
branches:
- master
paths:
- '.github/workflows/documentation.yml'
- 'package.json'
- 'docs/**'
- 'lib'
- 'test'
- 'scripts/website.js'
- 'CHANGELOG.md'
- 'CONTRIBUTING.md'
- 'index.pug'
permissions:
contents: read
jobs:
lint-documentation:
runs-on: ubuntu-latest
name: Lint Markdown files
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- name: Setup node
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version: 22
- run: npm install
- name: Lint MD-Files # run markdownlint
run: npm run lint-md
# enable when "eslint-markdown" can be used without errors
# - name: Lint JS-Files # run eslint to lint the code-blocks themself
# run: npm run lint-js
test-documentation:
runs-on: ubuntu-22.04
name: Test Generating Docs
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- run: git fetch --depth=1 --tags # download all tags for documentation
- name: Setup node
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
with:
node-version: 22
- run: npm install
- name: Setup MongoDB
run: |
wget -q https://downloads.mongodb.org/linux/mongodb-linux-x86_64-ubuntu2204-6.0.20.tgz
tar xf mongodb-linux-x86_64-ubuntu2204-6.0.20.tgz
mkdir -p ./data/db/27017 ./data/db/27000
printf "\n--timeout 8000" >> ./test/mocha.opts
./mongodb-linux-x86_64-ubuntu2204-6.0.20/bin/mongod --setParameter ttlMonitorSleepSecs=1 --fork --dbpath ./data/db/27017 --syslog --port 27017
sleep 2
./mongodb-linux-x86_64-ubuntu2204-6.0.20/bin/mongod --version
echo `pwd`/mongodb-linux-x86_64-ubuntu2204-6.0.20/bin >> $GITHUB_PATH
- name: Setup config
run: |
echo "module.exports = {uri:'mongodb://127.0.0.1:27017/mongoose_test'};" > ./.config.js
- run: npm run docs:clean
- run: npm run docs:generate
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: Documentation on: pull_request: paths: - '.github/workflows/documentation.yml' - 'package.json' - 'docs/**' - 'lib' - 'test' - 'scripts/website.js' - 'CHANGELOG.md' - 'CONTRIBUTING.md' - 'index.pug' push: branches: - master paths: - '.github/workflows/documentation.yml' - 'package.json' - 'docs/**' - 'lib' - 'test' - 'scripts/website.js' - 'CHANGELOG.md' - 'CONTRIBUTING.md' - 'index.pug' permissions: contents: read concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true jobs: lint-documentation: timeout-minutes: 30 runs-on: latchkey-small name: Lint Markdown files steps: - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Setup node uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 with: cache: 'npm' node-version: 22 - run: npm install - name: Lint MD-Files # run markdownlint run: npm run lint-md # enable when "eslint-markdown" can be used without errors # - name: Lint JS-Files # run eslint to lint the code-blocks themself # run: npm run lint-js test-documentation: timeout-minutes: 30 runs-on: latchkey-small name: Test Generating Docs steps: - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - run: git fetch --depth=1 --tags # download all tags for documentation - name: Setup node uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 with: cache: 'npm' node-version: 22 - run: npm install - name: Setup MongoDB run: | wget -q https://downloads.mongodb.org/linux/mongodb-linux-x86_64-ubuntu2204-6.0.20.tgz tar xf mongodb-linux-x86_64-ubuntu2204-6.0.20.tgz mkdir -p ./data/db/27017 ./data/db/27000 printf "\n--timeout 8000" >> ./test/mocha.opts ./mongodb-linux-x86_64-ubuntu2204-6.0.20/bin/mongod --setParameter ttlMonitorSleepSecs=1 --fork --dbpath ./data/db/27017 --syslog --port 27017 sleep 2 ./mongodb-linux-x86_64-ubuntu2204-6.0.20/bin/mongod --version echo `pwd`/mongodb-linux-x86_64-ubuntu2204-6.0.20/bin >> $GITHUB_PATH - name: Setup config run: | echo "module.exports = {uri:'mongodb://127.0.0.1:27017/mongoose_test'};" > ./.config.js - run: npm run docs:clean - run: npm run docs:generate
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.
- 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.
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
- Network fetches
This workflow runs 2 jobs per trigger. On Latchkey the same minutes cost up to 58% less than GitHub-hosted, with zero queue time.