apm/.github/workflows/docs.yml at 4b7e4118bb4250691fdcdfa6db44ce24dbdffc3d · microsoft/apm · 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: Deploy Docs

on:
  # Deploy docs only when a new APM version is released, so the published
  # site always matches the latest released binary (see microsoft/apm#641).
  # Primary entrypoint is workflow_call from the CI/CD Pipeline release job
  # (release: published does not fire when the release is created by
  # GITHUB_TOKEN -- a documented Actions safeguard against recursion).
  # The release: published trigger is kept as a safety net for human-cut
  # releases. PR runs build (no deploy) to catch breakage before merge.
  # Manual workflow_dispatch is supported for re-publishing the current docs.
  workflow_call:
    inputs:
      is_prerelease:
        description: 'Skip deploy when true (build-only). Defaults to false (deploy).'
        required: false
        type: boolean
        default: false
  release:
    types: [published]
  pull_request:
    paths:
      - 'docs/**'
      - 'src/apm_cli/cli.py'
      - 'src/apm_cli/commands/**'
      - 'scripts/check_cli_docs.py'
      - 'tests/unit/test_cli_docs_contract.py'
      - 'tests/integration/test_cli_docs_contract.py'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: "pages-${{ github.ref }}"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Setup Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '22'
          cache: 'npm'
          cache-dependency-path: 'docs/package-lock.json'

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: '3.12'

      - name: Install uv
        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
        with:
          enable-cache: true

      - name: Install Python test dependencies
        run: uv sync --frozen --extra dev

      - name: Install dependencies
        working-directory: ./docs
        run: npm ci

      - name: Test generated-link checker
        working-directory: ./docs
        run: npm run test:links

      - name: Test CLI registry contract
        run: >-
          uv run --frozen pytest
          tests/unit/test_cli_docs_contract.py
          tests/integration/test_cli_docs_contract.py
          -q

      - name: Build documentation
        working-directory: ./docs
        run: npm run build

      - name: Check CLI registry against rendered pages
        run: uv run --frozen python scripts/check_cli_docs.py docs/dist

      - name: Verify schema $id reachability
        # Asserts every JSON Schema's declared $id URL resolves to a
        # byte-identical file in the build output. Without this, a
        # schema move or $id typo would silently break every toolchain
        # that pinned to the canonical URL. Uses python3 stdlib only.
        run: python3 scripts/check_schema_ids.py

      - name: Upload build artifacts
        # NOTE: in a reusable workflow, github.event_name reflects the CALLER's
        # event (here: 'push' of a v* tag from build-release.yml), NOT
        # 'workflow_call'. Detect the workflow_call invocation via the tag-push
        # context instead. PR runs (event_name == 'pull_request') correctly
        # build-only because none of the three branches match.
        if: |
          github.event_name == 'workflow_dispatch' ||
          (github.event_name == 'release' && github.event.release.prerelease == false) ||
          (github.event_name == 'push' && github.ref_type == 'tag' && inputs.is_prerelease == false)
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: docs/dist

  deploy:
    needs: build
    # Only stable releases (or manual dispatch) update the public docs site,
    # so prerelease tags (vX.Y.Z-rc1, etc.) don't clobber published docs.
    # NOTE: in a reusable workflow, github.event_name reflects the CALLER's
    # event ('push' of a v* tag from build-release.yml), NOT 'workflow_call'.
    if: |
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'release' && github.event.release.prerelease == false) ||
      (github.event_name == 'push' && github.ref_type == 'tag' && inputs.is_prerelease == false)
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1