Merge pull request #30 from automatiabcn/session/audit-fixes-20260604 #16
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # T-R07 — docs.automatiabcn.com build + deploy with mike versioning + Algolia. | |
| # Security: every interpolation routes through `env:` blocks. Sources used: | |
| # secrets.ALGOLIA_APP_ID, secrets.ALGOLIA_SEARCH_KEY, inputs.version (a | |
| # workflow_dispatch input with a default value), github.event_name. None are | |
| # untrusted PR/issue text. | |
| name: docs | |
| on: | |
| push: | |
| branches: [main] | |
| paths: | |
| - "docs/**" | |
| - "mkdocs.yml" | |
| - "scripts/gen_api_reference.py" | |
| - "scripts/build_docs.sh" | |
| - ".github/workflows/docs.yml" | |
| release: | |
| types: [published] | |
| workflow_dispatch: | |
| inputs: | |
| version: | |
| description: 'Version label (mike alias). Defaults to `latest`.' | |
| required: false | |
| default: 'latest' | |
| permissions: | |
| contents: write | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: pages | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 # mike needs full history to push to gh-pages | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.13" | |
| cache: pip | |
| - name: Install backend deps (for api-reference gen) | |
| working-directory: core/backend | |
| run: pip install -e . | |
| - name: Install docs deps | |
| run: | | |
| # Sprint 2G ITEM 3 — dropped `mkdocs-algolia-docsearch>=0.4`: | |
| # the PyPI package never existed, so `pip install` failed on | |
| # every docs.yml run since T-R07 (Sprint 18). The matching | |
| # `algolia_docsearch:` plugin entry has been removed from | |
| # mkdocs.yml. MkDocs Material's built-in search covers site | |
| # search; Algolia DocSearch can be re-introduced later as a | |
| # template override (no PyPI plugin). | |
| pip install \ | |
| "mkdocs-material[imaging]>=9.5" \ | |
| "mike>=2.1" | |
| - name: Configure git author for mike | |
| run: | | |
| git config --global user.name "abs-docs-bot" | |
| git config --global user.email "docs@automatiabcn.com" | |
| - name: Generate static api-reference.md | |
| run: bash scripts/build_docs.sh | |
| - name: Resolve mike version label | |
| # Sprint 2N.2 closeout: derive MIKE_VERSION from git ref so the | |
| # version label never collides with the `latest` alias. Pre-fix | |
| # the workflow defaulted MIKE_VERSION to "latest", which made | |
| # `mike deploy --update-aliases latest latest` try to deploy a | |
| # version named "latest" with alias "latest". On the second run | |
| # that errors `duplicated version and alias`, and the bare | |
| # `mike delete latest` only removes the alias, not the version. | |
| # | |
| # Rule now: | |
| # - tag push → MIKE_VERSION = the tag (e.g. v1.0.3) | |
| # - main push → MIKE_VERSION = "main" | |
| # - release → MIKE_VERSION = release tag | |
| # - dispatch → MIKE_VERSION = workflow input | |
| # The `latest` alias is updated every run via `--update-aliases`. | |
| if: github.event_name != 'pull_request' | |
| id: mike_version | |
| env: | |
| REF_NAME: ${{ github.ref_name }} | |
| EVENT_NAME: ${{ github.event_name }} | |
| DISPATCH_VERSION: ${{ inputs.version }} | |
| run: | | |
| set -euo pipefail | |
| if [ -n "$DISPATCH_VERSION" ] && [ "$DISPATCH_VERSION" != "latest" ]; then | |
| VERSION="$DISPATCH_VERSION" | |
| elif [ "$EVENT_NAME" = "push" ] && [[ "$REF_NAME" == v* ]]; then | |
| VERSION="$REF_NAME" | |
| elif [ "$EVENT_NAME" = "release" ]; then | |
| VERSION="$REF_NAME" | |
| else | |
| VERSION="main" | |
| fi | |
| echo "version=${VERSION}" >> "$GITHUB_OUTPUT" | |
| - name: Deploy with mike (versioned, idempotent) | |
| if: github.event_name != 'pull_request' | |
| env: | |
| ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }} | |
| ALGOLIA_SEARCH_KEY: ${{ secrets.ALGOLIA_SEARCH_KEY }} | |
| MIKE_VERSION: ${{ steps.mike_version.outputs.version }} | |
| run: | | |
| set -euo pipefail | |
| git fetch origin gh-pages --depth=1 2>/dev/null || true | |
| # Idempotent pre-delete — keep stderr visible so a real error | |
| # (auth, network) doesn't hide behind `|| true`; a "version | |
| # not found" exits non-zero but is expected on first run. | |
| mike delete --push "${MIKE_VERSION}" || \ | |
| echo "==> mike delete: version not present (first run or rerun)" | |
| mike deploy --push --update-aliases "${MIKE_VERSION}" latest | |
| mike set-default --push latest | |
| - name: Build site (PR preview only) | |
| if: github.event_name == 'pull_request' | |
| env: | |
| ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }} | |
| ALGOLIA_SEARCH_KEY: ${{ secrets.ALGOLIA_SEARCH_KEY }} | |
| run: mkdocs build --strict | |
| - uses: actions/upload-pages-artifact@v3 | |
| if: github.event_name == 'pull_request' | |
| with: | |
| path: ./site |