ci: post bazelbuild/bazel preview comments via dedicated GitHub App (#400)

[alan707]

Summary

Migrates the docs-preview comment-posting path on bazelbuild/bazel PRs off the human-tied BAZELBUILD_BAZEL_PAT personal access token and onto a dedicated, least-privilege GitHub App ("Bazel Docs PR Commenter"). PATs inherit a person's full access and are discouraged for service accounts; an App is a scoped service identity. Closes #400.

The preview build path already used a GitHub App (GH_APP_ID) to push pr-<N> branches to this repo. This change brings the upstream write path to the same model.

What changed

• comment job mints a scoped installation token via actions/create-github-app-token@v3 (owner: bazelbuild, repositories: bazel) from new secrets BAZEL_PR_COMMENTER_APP_ID / BAZEL_PR_COMMENTER_PRIVATE_KEY, and posts/updates the preview comment with it instead of the PAT.
• The token step is continue-on-error: true. Graceful degradation: until a Bazel org owner installs the App on bazelbuild/bazel, previews still build and the comment step skips (logging the URL it would have posted). Same safe behavior as today's unset-PAT path.
• list-prs and cleanup dropped the PAT entirely; those are public reads, so the repo's own github.token suffices. (Verified in production: with the PAT already unset, these jobs have been reading bazelbuild/bazel via github.token on every cron run.)
• README.md: secrets table updated to the two App secrets, plus a short note on the App scope.
• .gitignore: ignore *.pem so private keys can't be committed.

App permission scope

The App needs exactly one permission on bazelbuild/bazel: Issues: Read & write.

A PR conversation comment is created via the issue-comments REST endpoint (POST /repos/{o}/{r}/issues/{n}/comments), which GitHub's fine-grained permissions reference lists under Issues, not Pull requests (create is Issues-only; update/list accept either). The App token only ever calls the issue-comments endpoints. Every /pulls/* read in the workflow runs on github.token, so the App needs no Pull-requests access at all.

Remaining step (human-gated)

A bazelbuild org owner must install the App on bazelbuild/bazel (Issues: Read & write, that repo only). Until then this PR is a no-op regression-wise: it changes the identity used for an already-skipping path. The App secrets are already set on this repo.

Maintainer request template:

Subject: Approve install of "Bazel Docs PR Commenter" GitHub App on bazelbuild/bazel

bazel-contrib/bazel-docs runs the docs-preview bot that comments a rendered Mintlify preview link on bazelbuild/bazel PRs that touch docs/. It currently posts using a personal access token, which we want to retire in favor of a scoped service account. Could an org owner install our GitHub App "Bazel Docs PR Commenter" (owned by the bazel-contrib org) on bazelbuild/bazel only, with a single permission:

• Issues: Read and write — post/update the preview comment (a PR conversation comment is created via the issue-comments REST endpoint, governed by the Issues permission).

No contents, pull-requests, or org-level access. No webhooks. Tracking issue: #400.

Test plan

• Workflow YAML validates (ruby -ryaml).
• github.token cross-repo reads of bazelbuild/bazel confirmed against the last several production cron runs (0 auth failures; cleanup read 58 PR states successfully).
• After merge + App install: manually dispatch Preview Bazel docs PRs with a pr_number touching docs/; confirm the "Mint upstream comment token" step succeeds and a comment posts as bazel-docs-pr-commenter[bot].

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
bazel	🟢 Ready	View Preview	May 29, 2026, 4:54 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.