Distillation

Date: Sep 8, 2026

• 🔴 (20:18) User established that for fork pull requests, checkout should default to GITHUB_REF, whose pull-request merge SHA is always fetchable from the base repository using github.token.
• 🟡 (20:18) Commit ff574c983076aab38f1e657d9623bdee0c85ec65 (chore: regenerate docs), authored and committed by github-actions[bot] <github-actions[bot]@users.noreply.github.com> on Apr 23, 2026 at 18:27:54 UTC, represents a large generated baseline: 791 files changed with 217,091 insertions.
• 🟡 (20:18) In .github/workflows/ci.yml, the docs/skill generation job obtains a GitHub App token via actions/create-github-app-token@v3 for same-repository PRs and non-PR events, using vars.SENTRY_RELEASE_BOT_CLIENT_ID and secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY; fork PRs skip this because secrets are unavailable.
• 🟡 (20:18) .github/workflows/ci.yml uses actions/checkout@v6 with token: ${{ steps.token.outputs.token || github.token }} and ref: ${{ steps.token.outcome == 'success' && (github.head_ref || github.ref_name) || '' }}. Same-repository PRs check out the branch head so regenerated docs can be pushed; fork PRs leave ref empty to use the pull-request merge SHA.
• 🟡 (20:18) The CI generation flow uses pnpm/action-setup@v4, actions/setup-node@v6 with ${{ env.NODE_VERSION_22 }}, and actions/cache@v5; it caches node_modules, packages/*/node_modules, and apps/*/node_modules under node-modules-${{ hashFiles('pnpm-lock.yaml', '.npmrc', 'packages/cli/patches/**') }}, and runs pnpm install --frozen-lockfile on a cache miss.
• 🟡 (20:18) .github/workflows/ci.yml runs generation and validation in this order: pnpm run generate:schema, pnpm run generate:docs, then pnpm run check:fragments.
• 🟡 (20:18) CI checks generated skill freshness with git diff --quiet packages/cli/plugins/sentry-cli/skills/sentry-cli/ and generated docs-section freshness with git diff --quiet packages/cli/README.md packages/cli/DEVELOPMENT.md apps/cli-docs/src/content/docs/contributing.md apps/cli-docs/src/content/docs/self-hosted.md apps/cli-docs/src/content/docs/getting-started.mdx; either check emits stale=true via $GITHUB_OUTPUT when differences exist.
• 🟡 (20:18) For stale generated files on a branch with a successful bot-token step, CI configures github-actions[bot], stages the generated skill directory plus the five generated documentation files, and runs git diff --cached --quiet || (git commit -m "chore: regenerate docs" && git push). For fork PRs without the bot token, stale files instead fail CI with Generated files are out of date. Run 'pnpm run generate:docs' locally and commit the result.
• 🟡 (20:18) packages/cli/script/check-fragments.ts is a #!/usr/bin/env tsx validator supporting tsx script/check-fragments.ts for warnings and tsx script/check-fragments.ts --strict for errors on missing subcommand coverage.
• 🟡 (20:18) Before importing the route tree, packages/cli/script/check-fragments.ts ensures src/generated/skill-content.ts exists; if absent, it creates src/generated/ recursively and writes export const SKILL_FILES: [string, string][] = [];\n.
• 🟡 (20:18) Fragment validation derives routes dynamically from routes in ../src/app.js using extractAllRoutes() from ../src/lib/introspect.js, skips the help route via SKIP_ROUTES, and expects one Markdown fragment per route plus index.md under ${DOCS_FRAGMENTS}/commands.
• 🟡 (20:18) packages/cli/script/check-fragments.ts reports: missing fragments for routes; stale fragments with no matching route; fragment files containing YAML frontmatter; fragment files containing <!-- GENERATED:END -->; and a missing required top-level ${DOCS_FRAGMENTS}/configuration.md.
• 🟡 (20:18) Subcommand coverage in packages/cli/script/check-fragments.ts accepts three forms: 1. a full command reference such as sentry dashboard revisions anywhere in the fragment, 2. for a route’s default command, a bare sentry <route> matched without accidentally accepting a longer subcommand invocation, or 3. a level 1–4 Markdown heading containing the leaf subcommand name outside fenced code blocks.
• 🟡 (20:18) The fragment validator removes fenced backtick or tilde code blocks using FENCED_CODE_BLOCK_RE before heading checks, preventing bash comments inside code blocks from being misread as Markdown headings.
• 🟡 (20:18) getMultiCommandRoutes() excludes standalone routes only when they have at most one command and that command path is exactly sentry <route-name>; findDefaultInRouteMap() identifies a default subcommand by object-reference comparison between target.getDefaultCommand() and targets returned by target.getAllEntries().