AirStack/.github/workflows/deploy_docs_from_develop.yaml at main · castacks/AirStack · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
name: Build/Publish Develop Docs
on:
  push:
    paths:
      - "docs/**"
      - "mkdocs.yml"
      - "*.md"
      - "stacks/**"
      - "tools/gen_docs_catalog.py"
      - ".github/workflows/deploy_docs_from_develop.yaml"
    branches:
      - develop
  # Module-docs freshness (RFC #379 §9): the catalog is regenerated from the
  # live registry on every deploy, so a registry change only reaches the site
  # when a deploy runs. Until registry-driven repository_dispatch lands
  # ("within a day, exact at releases"), a weekly rebuild plus manual dispatch
  # keeps the develop catalog from going stale.
  workflow_dispatch:
  schedule:
    - cron: "17 6 * * 1" # weekly, Mondays 06:17 UTC
# Serialize gh-pages pushes: concurrent docs deploys race on the branch
# push (observed: develop deploy rejected with 'fetch first' when the main
# deploy pushed at the same time).
concurrency:
  group: docs-deploy-gh-pages
  cancel-in-progress: false
permissions:
  contents: write
  issues: write # drift alarm files an issue when the committed catalog lags the registry
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # schedule/workflow_dispatch run on the default branch; this
          # workflow always publishes the develop docs.
          ref: develop
          fetch-depth: 0
      - uses: actions/setup-python@v4
        with:
          python-version: 3.10.6
      - name: Install Dependencies
        run: |
          pip install mkdocs-material mkdocs-same-dir mkdocs-redirects pyyaml
          pip install pillow cairosvg mike
      # DRIFT ALARM: the committed docs/modules pages + the fixture index
      # (tests/meta/fixtures/modules_index/) must mirror the LIVE registry.
      # A merged trunk PR with an unmerged registry PR — or vice versa —
      # otherwise publishes a catalog that silently disagrees with git
      # (this happened with `mighty`, 2026-08-29). Develop deploy only:
      # main/release committed pages intentionally lag develop. NEVER fails
      # the deploy (the regeneration below publishes the current catalog
      # regardless); it just makes the mismatch loud — a warning annotation,
      # a job summary, and at most one open issue. The sync-modules-index
      # workflow opens the PR that clears it.
      - name: Catalog drift alarm (committed pages vs live registry)
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          rm -rf .modules-index-drift
          git clone --depth 1 https://github.com/castacks/airstack-modules-index .modules-index-drift \
            || { echo "skipped: registry unreachable — no drift verdict"; exit 0; }
          mkdir -p /tmp/no-fetched-modules
          if python3 tools/gen_docs_catalog.py --index .modules-index-drift \
               --modules-dir /tmp/no-fetched-modules --check 2> drift.txt; then
            echo "committed catalog is in sync with the live registry"
            exit 0
          fi
          echo "::warning title=Module catalog drift::committed docs/modules + fixture disagree with the live registry. The published catalog is regenerated and current; trunk needs a sync PR — run the sync-modules-index workflow."
          { echo "## Module catalog drift"; echo; echo '```'; head -c 5000 drift.txt; echo '```'; } >> "$GITHUB_STEP_SUMMARY"
          if [ -z "$(gh issue list --label docs-catalog-drift --state open --json number --jq '.[].number')" ]; then
            gh label create docs-catalog-drift --color D93F0B \
              --description "Committed module catalog disagrees with the live registry" 2>/dev/null || true
            gh issue create --title "Module catalog drift: committed docs/modules disagrees with the live registry" \
              --label docs-catalog-drift \
              --body "$(printf 'Detected by the develop docs deploy: %s/%s/actions/runs/%s\n\nThe committed docs/modules pages + tests/meta/fixtures/modules_index/ do not match regeneration from the live airstack-modules-index (usually a registry PR merged without its trunk sync, or the reverse). The published develop catalog is regenerated live and stays correct; git is what lags.\n\nFix: run the **sync-modules-index** workflow (Actions tab) and merge its PR — or sync manually per the extract-module skill registration step.\n\n```\n%s\n```' "$GITHUB_SERVER_URL" "$GITHUB_REPOSITORY" "$GITHUB_RUN_ID" "$(head -c 5000 drift.txt)")"
          else
            echo "drift issue already open — not filing a duplicate"
          fi
      # RFC #379 §9: module docs ride the docs deploy. Shallow-clone the
      # registry index and each REGISTERED module repo at its registered_ref
      # into the gitignored modules/ dir, then regenerate docs/modules/ so
      # the published catalog is fresh even when the committed pages lag.
      # FAILURE ISOLATION: nothing in this step may fail the deploy — an
      # unreachable registry or module repo degrades to the committed pages /
      # a stub note on the module's page.
      - name: Fetch registry index and registered module repos
        run: |
          rm -rf .modules-index modules
          git clone --depth 1 https://github.com/castacks/airstack-modules-index .modules-index \
            || echo "skipped: registry index unreachable (committed catalog pages will be served)"
          if [ -d .modules-index/modules ]; then
            mkdir -p modules
            python3 tools/gen_docs_catalog.py --index .modules-index --list-refs |
            while IFS=$'\t' read -r name repo ref; do
              ( git init -q "modules/$name" \
                && git -C "modules/$name" remote add origin "$repo" \
                && git -C "modules/$name" fetch -q --depth 1 origin "$ref" \
                && git -C "modules/$name" checkout -q FETCH_HEAD ) \
                || { rm -rf "modules/$name"; echo "skipped: module $name ($repo @ $ref) unreachable — its page keeps the stub note"; }
            done
            python3 tools/gen_docs_catalog.py --index .modules-index --modules-dir modules \
              || echo "skipped: catalog regeneration failed (committed pages will be served)"
          fi
      - name: Setup Docs Deploy
        run: |
          git config --global user.name "Docs Deploy"
          git config --global user.email "docs.deploy@example.co.uk"
      - name: Build Docs Website
        env:
          # "Edit this page" links on the develop docs edit the develop
          # branch (mkdocs.yml defaults edit_uri to edit/main/).
          DOCS_EDIT_URI: edit/develop/
        run: |
          VERSION=$(grep -m1 '^VERSION=' .env | cut -d= -f2- | tr -d '"')
          mike deploy --push --title "${VERSION} (unstable)" develop
      # mike re-sorts versions.json on every deploy, so pin develop — the
      # higher, unreleased version — back to the top of the version selector
      # after each deploy.
      - name: Reorder version selector (develop first)
        run: |
          git worktree add ../ghp-reorder gh-pages
          python3 .github/workflows/scripts/docs_reorder_versions.py ../ghp-reorder/versions.json
          if ! git -C ../ghp-reorder diff --quiet -- versions.json; then
            git -C ../ghp-reorder commit -m "Reorder version selector: develop above main" versions.json
            git push origin gh-pages
          fi
          git worktree remove ../ghp-reorder