release: v0.8.0 #37
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
| name: Docs | |
| # Builds the VitePress documentation site (docs/) and deploys it to GitHub Pages | |
| # on a release tag. The site is an isolated workspace with its own package.json | |
| # and lockfile, so it never touches the CLI package's dependency closure. | |
| # | |
| # The site documents the *published* version, not main. docs/commands.md is | |
| # generated from the CLI's own `--help`, so deploying from main would publish | |
| # flags and behaviour that `npm i -g @pungoyal/kite-cli` does not yet ship — the | |
| # same docs-rot this repo treats as dangerous, just pointing forwards. Deploys | |
| # therefore ride the `v*` tag that publishes to npm, so the two move together. | |
| # | |
| # On pull requests and on main the build still runs as a validation gate — | |
| # `vitepress build` fails on a broken build or a dead internal link | |
| # (ignoreDeadLinks is off), so regressions are caught before merge rather than | |
| # at release time. `workflow_dispatch` from main is the escape hatch for | |
| # publishing a documentation fix without cutting a release. | |
| # | |
| # `paths` is deliberately absent from `push`: path filters and tag filters | |
| # interact badly (a tag push carries no meaningful file diff), and the build is | |
| # a ~20-second job, so it simply runs on every push to main and every tag. | |
| on: | |
| push: | |
| branches: [main] | |
| tags: ['v*'] | |
| pull_request: | |
| paths: | |
| - 'docs/**' | |
| - '.github/workflows/docs.yml' | |
| workflow_dispatch: | |
| # Least privilege by default; the deploy job opts into what Pages needs. | |
| permissions: | |
| contents: read | |
| # Serialise real deployments (one Pages group per ref) without letting a PR | |
| # build block main's deploy or vice versa. | |
| concurrency: | |
| group: pages-${{ github.ref }} | |
| cancel-in-progress: false | |
| jobs: | |
| build: | |
| name: Build site | |
| runs-on: ubuntu-latest | |
| steps: | |
| # Actions are pinned to full commit SHAs, not tags — tags are mutable and | |
| # a compromised upstream can repoint them (cf. the tj-actions breach). | |
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v5 | |
| with: | |
| # VitePress' lastUpdated timestamps read git history, not the tree. | |
| fetch-depth: 0 | |
| - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 | |
| with: | |
| node-version: '24' | |
| cache: npm | |
| cache-dependency-path: docs/package-lock.json | |
| # --ignore-scripts blocks dependency lifecycle hooks, the vector used by | |
| # the Shai-Hulud worm. `npm ci` never resolves outside the lockfile. | |
| - name: Install docs dependencies | |
| run: npm ci --ignore-scripts | |
| working-directory: docs | |
| # The validation gate: fails the check on a broken build or dead link, on | |
| # pull requests and on main as well as on the tag that deploys. | |
| - name: Build | |
| run: npm run build | |
| working-directory: docs | |
| # A manual deploy from a branch is the one path that can publish a command | |
| # reference the released package does not match — the drift this workflow | |
| # exists to prevent, reachable by one button. So check it rather than trust | |
| # the operator: install the published CLI, regenerate the reference from | |
| # *its* `--help`, and fail if what would be deployed differs. Dispatching | |
| # from a `v*` tag needs no check — CI already proved the reference matches | |
| # that tag's source. | |
| - name: Verify the command reference matches the published CLI | |
| if: github.event_name == 'workflow_dispatch' && !startsWith(github.ref, 'refs/tags/v') | |
| run: | | |
| npm ci --ignore-scripts | |
| npm install --prefix "$RUNNER_TEMP/published" --no-save --ignore-scripts @pungoyal/kite-cli@latest | |
| KITE_DOCS_CLI="$RUNNER_TEMP/published/node_modules/@pungoyal/kite-cli/dist/cli.js" \ | |
| node scripts/generate-command-reference.mjs --check | |
| # Pages plumbing is only meaningful on a real deployment — a tag push or a | |
| # manual dispatch. A PR or a plain push to main stops at the build above. | |
| - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 | |
| if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch' | |
| - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 | |
| if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch' | |
| with: | |
| path: docs/.vitepress/dist | |
| deploy: | |
| name: Deploy to Pages | |
| # Only a release tag (or a deliberate manual dispatch) publishes. Everything | |
| # else — pull requests, ordinary pushes to main — is a build-only gate. | |
| if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch' | |
| needs: build | |
| runs-on: ubuntu-latest | |
| permissions: | |
| pages: write # deploy to Pages | |
| id-token: write # OIDC token the deploy action verifies | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - id: deployment | |
| uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0 |