fix(github-mint): grant deployments:read so QA can read PR preview URLs

[guitavano]

Problema

O QA agent aprovou a faststoretorra#204 reportando previewUrl: null — "check FastStore WebOps verde, mas a API de deployments retorna 403 para este token" — e teve que subir a aplicação no sandbox (bun run dev) para exercer a mudança, em vez de usar o preview da PR.

Causa raiz. TASK_BOARD_ITEM_PRS_GET resolve o previewUrl de 4 fontes (apps/api/src/tools/task-board/prs-get.ts). Para VTEX FastStore WebOps o preview é publicado só como um GitHub Deployment — não como target_url de commit-status nem comentário de bot — então a única fonte que o encontra é o último recurso GET_PREVIEW_DEPLOYMENT (Deployments API). Conexões repo-scoped mintam seu installation token a partir de GITHUB_SCOPED_PERMISSIONS, que nunca pedia deployments → a chamada retorna 403 Resource not accessible by integration e previewUrl volta null.

Companheiro do decocms/mcps#535 (que adicionou a tool GET_PREVIEW_DEPLOYMENT): a tool lê com o token do caller, e faltava conceder deployments:read a esse token.

Correção

• Adiciona deployments: "read" a GITHUB_SCOPED_PERMISSIONS.
• Generaliza o fallback checks-only (mintRepoTokenWithChecksFallback) num ladder agnóstico de permissão (mintRepoTokenWithFallback + OPTIONAL_MINT_PERMISSIONS), que descarta um read opcional por vez (deployments, depois checks) quando o mint é rejeitado especificamente por exceder o que a instalação/allowlist concede:
  • instalação com checks mas sem o mais novo deployments → mantém checks;
  • instalação sem nenhum dos dois → ainda minta um token de código funcional;
  • portanto não dá 422-break em import/refresh de orgs que ainda não reaprovaram o upgrade de permissão.
• withOptionalReadPermissions self-heala recipes legadas no re-mint (~1h).

Depende de (fora deste repo)

Só tem efeito pleno quando: (1) o GitHub App do deco declarar deployments:read, (2) cada org reaprovar a instalação, e (3) o allowlist do MINT_REPO_TOKEN (github-mcp) permitir deployments. Até lá o ladder degrada graciosamente (comportamento idêntico ao de hoje).

Testes

• packages/shared/src/github-repo-scope.test.ts — reescritos para o ladder: sucesso first-try, drop só de deployments (mantém checks), drop de ambos, erro não relacionado não descarta optionals, rejeição de permissão required só surfa depois que os optionals acabam. bun test verde (42 pass).
• bun run check (shared/api/web), bun run lint (0 erros), bun run fmt, knip — todos limpos para os símbolos alterados.

🤖 Generated with Claude Code

---

Summary by cubic

Grant deployments:read to repo-scoped tokens and add a permission-agnostic mint fallback so the PR panel can read PR preview URLs via GitHub Deployments. Previously we did not request deployments and GET_PREVIEW_DEPLOYMENT 403’d, leaving previewUrl null; now we request it and shed optional reads (deployments, then checks) only when the installation or allowlist rejects them.

• Review notes

  • Adds deployments: "read" to GITHUB_SCOPED_PERMISSIONS; keeps existing write scopes.
  • Replaces mintRepoTokenWithChecksFallback with mintRepoTokenWithFallback, driven by OPTIONAL_MINT_PERMISSIONS and withOptionalReadPermissions.
  • Updates apps/api/src/oauth/github-mint.ts and apps/web/src/lib/provision-repo-scoped-github-connection.ts to use the new ladder; tokens self-heal optionals on re-mint.
  • Extends tests in packages/shared/src/github-repo-scope.test.ts to cover deployments, ladder behavior, and non-downgrade errors.

• Rollout

  • Update the GitHub App to declare deployments:read, have orgs re-approve the installation, and permit deployments in the MINT_REPO_TOKEN allowlist.
  • No breaking changes before re-approval: the ladder downgrades gracefully and preserves checks when available.

^{Written for commit 328c3c0. Summary will update on new commits.}