feat(api-docs): Build the API reference from @sentry/api/docs

.github/workflows/bump-api-schema-sha.yml

@@ -1,15 +1,22 @@
-name: Bump API Schema SHA
+name: Bump @sentry/api
 on:
-  # This could be run manually, but the general expectation is that this fires
-  # from GHA in getsentry/sentry-api-schema on changes there. See:
+  # The API reference is built from the pinned @sentry/api version. getsentry/sentry
+  # releases it whenever the API spec changes; this picks up the new version. See:
   #
   #   https://develop.sentry.dev/api/public/#build-process
-
+  #
+  # The file keeps its old name so existing dispatches still reach it.
+  schedule:
+    - cron: '17 * * * *'
   workflow_dispatch:
+# A dispatch and the hourly run must not both push the same bump branch.
+concurrency:
+  group: bump-sentry-api
+  cancel-in-progress: false
 jobs:
   release:
     runs-on: ubuntu-latest
-    name: 'Bump API Schema SHA'
+    name: 'Bump @sentry/api'
     steps:
       - name: Get auth token
         id: token
@@ -18,53 +25,18 @@ jobs:
           app-id: ${{ vars.SENTRY_API_SCHEMA_UPDATER_APP_CLIENT_ID }}
           private-key: ${{ secrets.SENTRY_API_SCHEMA_UPDATER_PRIVATE_KEY }}
           owner: getsentry
-          repositories: |
-            sentry-docs
-            sentry-api-schema
+          repositories: sentry-docs
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           token: ${{ steps.token.outputs.token }}
-      - name: 'Bump API Schema SHA'
-        shell: bash
+      - uses: pnpm/action-setup@02f6c237bd2518259fed6c71566509edfb3f2b74 # v4
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v4
+        with:
+          node-version-file: 'package.json'
+      - name: 'Bump @sentry/api'
         env:
           # An elevated token is necessary because with plain github.token
           # GitHub does not recursively call workflows, which means CI does not
           # kick off for the PR we're about to create.
           GITHUB_TOKEN: ${{ steps.token.outputs.token }}
-        run: |
-          set -euo pipefail
-
-          git config user.email "271575301+sentry-api-schema-updater[bot]@users.noreply.github.com"
-          git config user.name "sentry-api-schema-updater[bot]"
-
-          filepath="src/build/resolveOpenAPI.ts"
-
-          # Authenticate to avoid the low unauthenticated rate limit, and fail on
-          # HTTP errors so an error body never gets written in as the SHA.
-          sha="$(curl -sSL --fail \
-            -H "Authorization: Bearer $GITHUB_TOKEN" \
-            -H 'Accept: application/vnd.github.VERSION.sha' \
-            'https://api.github.com/repos/getsentry/sentry-api-schema/commits/main')"
-
-          if [[ ! "$sha" =~ ^[0-9a-f]{40}$ ]]; then
-            echo "::error::Expected a 40-character commit SHA from the GitHub API, got: $sha"
-            exit 1
-          fi
-          echo "Latest commit to 'getsentry/sentry-api-schema' is $sha"
-
-          sed -i -e "s|^const SENTRY_API_SCHEMA_SHA =.*$|const SENTRY_API_SCHEMA_SHA = '$sha';|g" "$filepath"
-          echo "Updated $filepath"
-
-          if git diff --quiet "$filepath"; then
-            echo "No changes to $filepath, skipping."
-            exit 0
-          fi
-
-          branch="bot/bump-api-schema-to-${sha:0:8}"
-          git checkout -b "$branch"
-          git add "$filepath"
-          git commit -m "Bump API schema to ${sha:0:8}"
-          git push --set-upstream origin "$branch"
-
-          gh pr create --fill
-          gh pr merge --squash --admin -d
+        run: sh scripts/bump-sentry-api.sh

.pre-commit-config.yaml

@@ -23,6 +23,13 @@ repos:
       - id: flake8
       - id: fix-encoding-pragma
         args: ['--remove']
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+        args: ['--shell=sh', '--enable=check-extra-masked-returns']
+        # Older scripts are bash and predate this hook.
+        files: '^scripts/bump-sentry-api\.sh$'
   - repo: local
     hooks:
       - id: prettier

develop-docs/backend/api/public.mdx

@@ -390,29 +390,27 @@ When you open the pull request, please add a screenshot of the page or pages you
 
 ### Build Process
 
-The openapi-diff test will fail when CI runs on your pull request, this is expected and meant to
-highlight the diff. It is not required to merge.
+The `openapi-diff` workflow compares your pull request's schemas with master where your branch
+started. Its **Public API changelog** job lists your public API changes in the job summary and
+never fails. Its **RPC schema breaking changes** job fails when an RPC method changes in a way that
+breaks existing callers. To see the changelog locally, run `make build-api-docs`, then
+`make diff-api-docs`.
 
-Once you make changes to an endpoint and merge the change into Sentry, a series of GitHub Actions
-will be triggered to make your changes automatically go live:
+Once you make changes to an endpoint and merge the change into Sentry, these steps make your changes go live:
 
 1. The [openapi workflow in
-   sentry](https://github.com/getsentry/sentry/blob/master/.github/workflows/openapi.yml) updates
-   the schema in [sentry-api-schema](https://github.com/getsentry/sentry-api-schema) with the
-   OpenAPI build artifact.
-2. The [cascade-to-sentry-docs workflow in
-   sentry-api-schema](https://github.com/getsentry/sentry-api-schema/blob/main/.github/workflows/cascade-to-sentry-docs.yml)
-   reacts to the push to `main` in (1) by triggering the [bump-api-schema-sha workflow in
-   sentry-docs](https://github.com/getsentry/sentry-docs/blob/master/.github/workflows/bump-api-schema-sha.yml).
-3. The [bump-api-schema-sha workflow in
+   sentry](https://github.com/getsentry/sentry/blob/master/.github/workflows/openapi.yml) builds
+   the schema. When the schema changed since the last release, sentry releases a new version of
+   the [`@sentry/api`](https://www.npmjs.com/package/@sentry/api) package from
+   `static/packages/api`. The package's `@sentry/api/docs` export holds the API reference data.
+2. The [bump workflow in
    sentry-docs](https://github.com/getsentry/sentry-docs/blob/master/.github/workflows/bump-api-schema-sha.yml)
-   fetches the latest commit SHA from `sentry-api-schema` and writes it into the correct file, then
-   makes and merges a PR in `sentry-docs`, which kicks off a deploy via Vercel to
-   https://docs.sentry.io/api/.
+   runs hourly. When npm has a newer `@sentry/api`, it pins that version, then makes and merges
+   a PR in `sentry-docs`, which kicks off a deploy via Vercel to https://docs.sentry.io/api/.
 
 ## Troubleshooting API Docs Tests
 
-NOTE: The `openapi-diff` test is supposed to fail when CI runs on your pull request as it is meant to highlight the schema changes. It is not required to merge.
+NOTE: The **Public API changelog** job of `openapi-diff` never fails. Read its job summary to check your public API changes.
 
 **Problem**: `TypeError: Cannot read properties of null (reading 'type')`
 

package.json

@@ -65,6 +65,7 @@
     "@radix-ui/react-tooltip": "^1.1.4",
     "@radix-ui/themes": "^3.1.3",
     "@sentry-internal/global-search": "^1.3.0",
+    "@sentry/api": "2.1.0",
     "@sentry/browser": "11.6.0",
     "@sentry/conventions": "^0.33.0",
     "@sentry/nextjs": "11.6.0",

scripts/bump-sentry-api.sh

@@ -0,0 +1,44 @@
+#!/bin/sh
+# Pin @sentry/api, which the API reference is built from, to its newest npm
+# release, then open and merge a PR for it.
+#
+# Environment:
+#   GITHUB_TOKEN  A token that can push branches and merge PRs. A GitHub App
+#                 token, unlike github.token, also starts CI on the new PR.
+set -eu
+
+package=@sentry/api
+
+latest=$(timeout 60 npm view "$package" version)
+case $latest in
+  '' | *[!0-9.]*)
+    echo "::error::Expected a release version of $package from npm, got: $latest"
+    exit 1
+    ;;
+esac
+
+current=$(node -p 'require("./package.json").dependencies[process.argv[1]]' "$package")
+if [ "$current" = "$latest" ]; then
+  echo "$package is already $latest, skipping."
+  exit 0
+fi
+echo "Bumping $package from $current to $latest"
+
+timeout 600 pnpm add --save-exact --lockfile-only "$package@$latest"
+
+git config user.email "271575301+sentry-api-schema-updater[bot]@users.noreply.github.com"
+git config user.name "sentry-api-schema-updater[bot]"
+
+# A run that stopped before the merge leaves this branch, and maybe its PR,
+# behind. Overwrite the branch and reuse an open PR so the next run finishes.
+branch="bot/bump-sentry-api-to-$latest"
+git checkout -B "$branch"
+git add package.json pnpm-lock.yaml
+git commit -m "Bump $package to $latest"
+timeout 120 git push --force --set-upstream origin "$branch"
+
+open_prs=$(timeout 60 gh pr list --head "$branch" --state open --json number --jq length)
+if [ "$open_prs" = 0 ]; then
+  timeout 60 gh pr create --fill --head "$branch"
+fi
+timeout 120 gh pr merge "$branch" --squash --admin -d

scripts/tsconfig.json

@@ -1,16 +1,18 @@
 {
   // Used only when running scripts/algolia.ts via `tsx` (see .github/workflows/algolia-index.yml).
   // tsx loads .ts files through Node's CJS resolver. `rehype-prism-diff` (imported transitively
-  // via src/mdx.ts) only declares an "import" condition in its package.json `exports` map, so the
-  // CJS resolver fails with ERR_PACKAGE_PATH_NOT_EXPORTED. Aliasing the bare specifier to the
-  // package's real dist file makes tsx resolve it as a plain file and bypass the exports map.
+  // via src/mdx.ts) and `@sentry/api/docs` (via src/build/resolveOpenAPI.ts) only declare an
+  // "import" condition in their package.json `exports` maps, so the CJS resolver fails with
+  // ERR_PACKAGE_PATH_NOT_EXPORTED. Aliasing each bare specifier to the package's real dist file
+  // makes tsx resolve it as a plain file and bypass the exports map.
   // Bun (the previous runner) tolerated the import-only exports map; tsx does not.
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "baseUrl": "..",
     "paths": {
       "sentry-docs/*": ["src/*"],
-      "rehype-prism-diff": ["node_modules/rehype-prism-diff/dist/index.js"]
+      "rehype-prism-diff": ["node_modules/rehype-prism-diff/dist/index.js"],
+      "@sentry/api/docs": ["node_modules/@sentry/api/dist/docs.js"]
     }
   }
 }