name: ci

# CI for the engineering handbook. This repo is docs-only (Markdown), so the
# gate lints Markdown and checks that links resolve.
#
# Naming is load-bearing: the org "main branch protection" ruleset matches the
# required status check against the JOB's check-run name, NOT "workflow / job".
# For a normal (non-reusable) job the check-run name IS the job name, so the job
# must be named literally "ci / ci" to emit that exact context. (A job named
# "ci" emits the context "ci" — which the PR UI cosmetically displays as
# "ci / ci" but does NOT satisfy the requirement.) This mirrors the org's
# aggregator-job convention in the `.github` repo's own self-CI.
#
# Both tools are configured to be green on the current content:
#   - markdownlint-cli2 reads .markdownlint-cli2.jsonc
#   - lychee reads lychee.toml (tolerates 429 so external flakiness never reds
#     an otherwise-valid docs change; broken internal links still fail)

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  ci:
    name: ci / ci
    runs-on: ubuntu-latest
    timeout-minutes: 10
    concurrency:
      group: ci-${{ github.workflow }}-${{ github.ref }}
      cancel-in-progress: true
    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: "24"

      - name: Markdown lint
        run: npx --yes markdownlint-cli2@0.23.0

      - name: Link check
        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0
        with:
          args: "--config lychee.toml --no-progress './**/*.md'"
          fail: true
        env:
          # Authenticated github.com requests avoid API rate-limit 429s.
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}