From d8dde7d119999c44e783546476fa01834fe6c8ee Mon Sep 17 00:00:00 2001 From: Will-thom <116388885+Will-thom@users.noreply.github.com> Date: Tue, 9 Jun 2026 23:26:01 -0300 Subject: [PATCH] docs: document github provider permissions --- .github/backlog/ISSUES.md | 2 + docs/github-provider-permissions.md | 108 ++++++++++++++++++++++++++++ docs/integrations.md | 1 + docs/permissions.md | 2 + docs/provider-context-plan.md | 1 + 5 files changed, 114 insertions(+) create mode 100644 docs/github-provider-permissions.md diff --git a/.github/backlog/ISSUES.md b/.github/backlog/ISSUES.md index 87eda5f..44fc343 100644 --- a/.github/backlog/ISSUES.md +++ b/.github/backlog/ISSUES.md @@ -674,6 +674,8 @@ Depends on: #79 and #82. Labels: `stage: 3`, `area: docs`, `area: github`, `good first contribution`, `oss first friendly`, `agent-friendly`, `status: ready` +Status: completed by [GitHub Provider Permissions](../../docs/github-provider-permissions.md). + Acceptance criteria: - List planned GitHub operations and required permissions. diff --git a/docs/github-provider-permissions.md b/docs/github-provider-permissions.md new file mode 100644 index 0000000..fdc3baa --- /dev/null +++ b/docs/github-provider-permissions.md @@ -0,0 +1,108 @@ +# GitHub Provider Permissions + +This document defines the planned permission posture for the optional Stage 3 GitHub provider adapter. + +PR Maven CLI remains local-first. The core Maven report analyzer does not need a GitHub token, does not call GitHub APIs, and must continue to work from local report artifacts only. + +Use this document with the [Provider Context Plan](provider-context-plan.md), [Provider Adapter Package Boundaries](provider-adapter-boundaries.md), [Provider Fixtures And Mocks](provider-fixtures-and-mocks.md), and [Provider Errors And Offline Fallbacks](provider-errors-and-fallbacks.md). + +Reference GitHub documentation: + +- [Permissions required for fine-grained personal access tokens](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens) +- [Use GITHUB_TOKEN for authentication in workflows](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token) + +## Permission Principles + +- Prefer read-only permissions. +- Keep provider access optional and explicit. +- Never require provider credentials for report-only Maven analysis. +- Do not request broad repository write permissions for initial provider context. +- Keep token handling out of core parser, mapper, formatter, and report packages. +- Degrade gracefully when provider context is unavailable. + +## Planned Operations + +| Planned operation | Purpose | Fine-grained token permission | GitHub Actions permission | Required for public repos | Required for private repos | +| --- | --- | --- | --- | --- | --- | +| Read pull request metadata | Identify PR number, base/head refs, and changed-file pagination context. | `Pull requests: read` | `pull-requests: read` | Optional when public API access is enough, but useful for rate limits and consistency. | Yes. | +| Read changed files for a pull request | Map changed paths back to Maven modules and explain relevance. | `Pull requests: read` | `pull-requests: read` | Optional when public API access is enough. | Yes. | +| Read check runs or check suites | Correlate local Maven findings with failing CI checks. | `Checks: read` | `checks: read` | Optional when public API access is enough. | Yes, when check-run context is requested. | +| Read workflow runs, jobs, logs, or artifacts | Find CI artifact locations or failing workflow context when that behavior is explicitly added. | `Actions: read` | `actions: read` | Optional when public API access is enough. | Yes, when workflow context is requested. | +| Read commit statuses | Support repositories that still expose status contexts outside Checks API. | `Commit statuses: read` | `statuses: read` | Optional when public API access is enough. | Yes, when status context is requested. | +| Read repository contents | Load provider-side config or map files only if a future issue explicitly scopes that behavior. | `Contents: read` | `contents: read` | Optional and not part of the initial changed-files adapter. | Only if that behavior is implemented. | +| Read repository metadata | Resolve repository identity and basic visibility details. | `Metadata: read` | Covered by the workflow token baseline. | Usually available for public repositories. | Yes. | + +The initial GitHub adapter should not create comments, annotations, statuses, labels, branches, commits, releases, or merges. + +## Public Repository Behavior + +For public repositories, provider context should support a no-token or anonymous mode when GitHub permits the requested read operation. + +No-token public behavior must still be treated as best effort: + +- rate limits may be lower; +- some endpoints may require authentication even for public data; +- missing provider context must not hide local Maven findings; +- diagnostics should explain that provider context was unavailable or partial. + +The local analyzer path remains fully supported without provider context. + +## Private Repository Behavior + +For private repositories, GitHub provider context requires an explicit token with the narrowest read permissions needed for the requested operation. + +Recommended minimums: + +- changed-files context: `Pull requests: read` and `Metadata: read`; +- check-run context: `Checks: read` and `Metadata: read`; +- workflow-run or artifact context: `Actions: read` and `Metadata: read`; +- legacy status context: `Commit statuses: read` and `Metadata: read`; +- repository-content reads: `Contents: read` only when the feature explicitly needs repository files. + +Private repository support must not make provider credentials mandatory for local report analysis. + +## No-Token Local Analyzer Behavior + +These commands must continue to work without GitHub credentials, provider environment variables, network access, or live API fixtures: + +- report discovery; +- Maven module discovery; +- Surefire and Failsafe parsing; +- Checkstyle, SpotBugs, and JaCoCo parsing; +- text output; +- JSON output; +- report-only no-failure behavior; +- output file writing. + +When provider context is requested but no usable token is available, the adapter should follow the fallback rules in [Provider Errors And Offline Fallbacks](provider-errors-and-fallbacks.md): + +- keep local Maven findings; +- mark provider context as unavailable or partial when the output contract supports it; +- emit a concise diagnostic for provider-aware modes; +- avoid converting provider errors into Maven findings. + +## Token Handling Expectations + +Future GitHub provider implementation should: + +- accept credentials through explicit provider wiring, CLI configuration, or well-documented CI environment behavior; +- never log token values; +- avoid storing tokens in fixtures, snapshots, or generated output; +- keep default tests credential-free; +- avoid reading provider environment variables from core analyzer packages; +- keep live-provider checks opt-in and skipped by default. + +## Non-Goals For The Initial Adapter + +The initial GitHub provider adapter should not: + +- post pull request comments; +- update commit statuses; +- create check-run annotations; +- approve, review, label, close, reopen, or merge pull requests; +- upload artifacts; +- read repository secrets; +- require write-scoped tokens; +- require a GitHub token for local Maven analysis. + +Any write operation must be introduced by a separate issue with explicit security, permission, test, and maintainer-review criteria. diff --git a/docs/integrations.md b/docs/integrations.md index 5214472..0859b42 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -27,6 +27,7 @@ Native PR and CI context adapters are planned for Stage 3. The planning lane is documented in the [Provider Context Plan](provider-context-plan.md). Package-boundary rules are documented in [Provider Adapter Package Boundaries](provider-adapter-boundaries.md). +GitHub token and read-permission expectations are documented in [GitHub Provider Permissions](github-provider-permissions.md). Planned order: diff --git a/docs/permissions.md b/docs/permissions.md index f39d02d..413408c 100644 --- a/docs/permissions.md +++ b/docs/permissions.md @@ -72,6 +72,8 @@ Core analyzer guardrails: - Production core code must not import network/provider clients. - Production core code must not read provider environment variables. +Future optional GitHub provider permissions are documented in [GitHub Provider Permissions](github-provider-permissions.md). Those permissions are for Stage 3 provider context only; they do not change the Stage 1 local analyzer contract. + Expected empty surfaces during stabilization: - GitHub Actions secrets. diff --git a/docs/provider-context-plan.md b/docs/provider-context-plan.md index b55eb52..9bc7d04 100644 --- a/docs/provider-context-plan.md +++ b/docs/provider-context-plan.md @@ -70,3 +70,4 @@ Ready design issues signal that contributors may start drafting contracts. Block Detailed package-boundary guidance lives in [Provider Adapter Package Boundaries](provider-adapter-boundaries.md). Fixture and fake-client guidance lives in [Provider Fixtures And Mocks](provider-fixtures-and-mocks.md). Provider failure behavior lives in [Provider Errors And Offline Fallbacks](provider-errors-and-fallbacks.md). +GitHub read-token expectations live in [GitHub Provider Permissions](github-provider-permissions.md).