@sentry/junior-github 0.67.3 → 0.69.0

package/SETUP.md

@@ -1,13 +1,13 @@
 # GitHub plugin setup
 
-This plugin exposes two skills — `github-code` (clone, source-code investigation, pull requests) and `github-issues` (issue workflows) — both authenticated via host-issued GitHub App installation tokens.
+This plugin exposes two skills — `github-code` (clone, source-code investigation, pull requests) and `github-issues` (issue workflows). Read operations use host-issued GitHub App installation tokens. Write operations use GitHub App user-to-server OAuth tokens so GitHub attributes the action to the requesting user with the app badge.
 
 ## 1) Create/install GitHub App
 
 In GitHub:
 
 1. Go to `Settings -> Developer settings -> GitHub Apps -> New GitHub App`.
-2. Set app name and callback URL (any valid HTTPS URL is fine if you do not use web flow).
+2. Set app name and callback URL to `https://<junior-host>/api/oauth/callback/github`.
 3. Under repository permissions, grant:
 
 - Issues: Read and write
@@ -23,6 +23,8 @@ In GitHub:
 Install the app on target repos/orgs and collect:
 
 - `GITHUB_APP_ID`
+- `GITHUB_APP_CLIENT_ID`
+- `GITHUB_APP_CLIENT_SECRET`
 - `GITHUB_APP_PRIVATE_KEY` (PEM)
 
 ## 2) Configure host runtime
@@ -30,6 +32,8 @@ Install the app on target repos/orgs and collect:
 Set on the harness host (never in skill files):
 
 - `GITHUB_APP_ID`
+- `GITHUB_APP_CLIENT_ID`
+- `GITHUB_APP_CLIENT_SECRET`
 - `GITHUB_APP_PRIVATE_KEY`
 - `GITHUB_INSTALLATION_ID`
 
@@ -39,16 +43,15 @@ under different app installations across orgs/accounts.
 
 ### Vercel env setup (multiline-safe)
 
-`GITHUB_APP_PRIVATE_KEY` is accepted as:
-
-- Raw PEM (multiline)
-- Escaped-newline PEM (single-line with `\n`)
-- Base64-encoded PEM
+`GITHUB_APP_PRIVATE_KEY` must be the PEM private key generated by GitHub for
+this app.
 
 For Vercel, prefer CLI file input so newlines are preserved exactly:
 
 ```bash
 vercel env add GITHUB_APP_ID production
+vercel env add GITHUB_APP_CLIENT_ID production
+vercel env add GITHUB_APP_CLIENT_SECRET production
 vercel env add GITHUB_INSTALLATION_ID production
 vercel env add GITHUB_APP_PRIVATE_KEY production --sensitive < ./github-app-private-key.pem
 ```
@@ -61,10 +64,41 @@ vercel env update GITHUB_APP_PRIVATE_KEY production --sensitive < ./github-app-p
 
 Repeat for `preview` and `development` as needed. After env changes, redeploy so the new deployment picks up updated values.
 
+### Optional permission overrides
+
+By default, `installation-read` grants read the app installation's current permission envelope once per process and scopes read-capable permissions down to `read` when requesting a token. To declare the app permission envelope in the plugin and avoid that installation lookup, pass `appPermissions` when registering the plugin:
+
+```ts
+githubPlugin({
+  appPermissions: {
+    contents: "read",
+    issues: "write",
+    pull_requests: "write",
+  },
+});
+```
+
+Junior records these permissions as plugin capabilities. Installation-read token requests remain read-only by requesting read-capable configured permissions at `read` level and omitting GitHub permission fields that have no `read` value. GitHub remains the source of truth for whether a permission name or level exists.
+
+GitHub App user-to-server tokens do not use OAuth scopes as their permission model. Their effective access is limited by the GitHub App's installed permissions, the app installation's repository access, and the requesting user's own GitHub access. GitHub returns an empty `scope` value for these tokens, so Junior cannot verify granted scopes from the token response.
+
+If you pass `additionalUserScopes`, Junior includes those values in the authorization URL and records the requested scope string as a local reauthorization contract. This does not expand or prove GitHub API permissions — configure GitHub App permissions with `appPermissions` and in the GitHub App settings for provider-enforced access:
+
+```ts
+githubPlugin({
+  additionalUserScopes: ["read:org", "workflow"],
+});
+```
+
+Use `additionalUserScopes` only when an integration flow requires specific GitHub OAuth scope parameters in the authorization URL. Do not rely on it to authorize repository, Actions, or workflow writes — those are enforced by GitHub App permissions and the requesting user's own access.
+
 ## 3) Runtime behavior
 
 - When either GitHub skill is active, authenticated `gh` and `git` commands cause the runtime to inject GitHub credentials automatically for the current turn.
-- Issued credentials are reused only within the current turn.
+- The plugin classifies GitHub traffic from the forwarded HTTP request. Safe app-readable API methods, GraphQL `GET`/`HEAD`/`OPTIONS` requests, and `git-upload-pack` use the `installation-read` grant. `GET /user` uses the `user-read` grant so account identity checks use the requester token. Write-specific REST URLs, non-read GraphQL methods, other non-read API methods, and `git-receive-pack` use the `user-write` grant.
+- `user-read` and `user-write` require the requester, or an explicitly delegated user subject from an allowed system run, to authorize the GitHub App through the private OAuth flow. Missing or expired user authorization pauses interactive turns, sends a private authorization link, and resumes after approval.
+- Git commits use the requester as the commit author, Junior as committer, and a Junior `Co-Authored-By` trailer.
+- Issued credentials are reused only within the current turn, credential leases are cached separately by plugin grant name, and upstream 403 permission denials clear the cached lease before the next retry.
 - Sandbox does not receive raw tokens via env; host applies Authorization header transforms for GitHub API calls.
 
 ## 4) CLI usage
@@ -84,16 +118,25 @@ git -C repo fetch --depth=50 origin
 git -C repo fetch --unshallow
 ```
 
-GitHub operations still require a GitHub skill to be active; the runtime injects credentials automatically when one is loaded:
+Load the relevant GitHub skill for command guidance and repo context:
 
 ```bash
 gh issue create --repo owner/repo --title "Example issue" --body-file /vercel/sandbox/tmp/issue.md
 ```
 
 `gh` supports either direct `GITHUB_TOKEN` (for local debugging) or sandbox-level header injection.
-The runtime uses `github.issues.read` for read-only issue commands, `github.issues.write` for issue edits, comments, and labels, `github.contents.write` for pushes and merge operations, and `github.pull-requests.write` for PR mutations after the branch is already on the remote.
+The plugin uses `installation-read` for read-only GitHub traffic and `user-write` for mutations. GitHub App permissions still need to cover the operation: issues for issue edits/comments/labels, contents for pushes and merges, pull requests for PR mutations, actions/workflows for workflow operations.
+
+Committing and pushing code uses more than one GitHub surface:
+
+- Creating the local Git commit does not call GitHub. Junior sets the requester as author and the GitHub App bot as committer in the sandbox.
+- Pushing a branch with Git smart HTTP (`git push`) uses the `user-write` grant and requires the GitHub App to have `Contents: write` on the target repository. The requesting user must also have write access to that repository.
+- REST Git database writes used by some `gh` flows also require `Contents: write`: create blob (`POST /git/blobs`), create tree (`POST /git/trees`), create commit (`POST /git/commits`), and create/update refs (`POST /git/refs`, `PATCH /git/refs/{ref}`). Changes to workflow files may also require `Workflows: write`.
+- Opening the PR after the branch exists is separate: `gh pr create --head` needs pull-request write permission, but it should not create or push commits itself.
+
+Fork creation is not part of the default PR path. `POST /repos/{owner}/{repo}/forks` uses the `user-write` grant, but GitHub requires `Administration: write` and `Contents: read`, and the app must be installed on both the source and destination accounts. Do not grant `Administration: write` for routine PR creation; push a branch explicitly and create the PR with `--head` instead.
 
-GitHub capability scoping is a safety rail, not a hard sandbox boundary. It helps prevent accidental write scope and wrong-repo mutations, and the host runtime still decides when to mint credentials. Credential injection is skill-scoped: load the relevant GitHub skill first, keep repo context explicit, and let the runtime choose the required capability for the command.
+GitHub App permission scoping is a safety rail, not a hard sandbox boundary. It helps prevent accidental write scope and wrong-repo mutations, and the host runtime still decides when to mint credentials. Credential injection is provider-domain scoped for sandbox traffic to `api.github.com` and `github.com` during turns with a signed credential context. Keep repo context explicit, and let the plugin choose the required grant for the outbound request.
 
 Be careful with mixed-surface PR commands:
 
@@ -128,23 +171,24 @@ jr-rpc config set github.repo getsentry/junior
 
 1. Confirm host env vars are present in prod:
    - `GITHUB_APP_ID`
+   - `GITHUB_APP_CLIENT_ID`
+   - `GITHUB_APP_CLIENT_SECRET`
    - `GITHUB_APP_PRIVATE_KEY`
    - `GITHUB_INSTALLATION_ID`
 2. Confirm the GitHub App is installed on your test repo with the permissions above.
 3. Deploy `main` to prod.
 4. Exercise `github-issues` to create an issue in a safe test repo.
-5. Verify the issue is authored by the GitHub App identity.
+5. Verify the issue is authored by the requesting GitHub user with the GitHub App badge.
 6. Exercise `github-issues` to update title/body, add/remove labels, and add a comment.
 7. Push a test branch and exercise `github-code` to create a draft PR using explicit repo targeting and `--head`.
-8. Verify all mutations succeed and are attributed to the app.
+8. Verify all mutations succeed and are attributed to the requesting GitHub user with the app badge.
 9. Verify GitHub API calls succeed while this skill is active without writing tokens into sandbox env/files.
 10. Verify raw token values are never printed in output or logs.
 11. Check logs for:
 
-- `credential_issue_request`
-- `credential_issue_success`
-- `credential_inject_start`
-- `credential_inject_cleanup`
+- `sandbox_egress_upstream_request`
+- `sandbox_egress_credential_needed`
+- `sandbox_egress_upstream_auth_rejected`
 
 12. Verify logs contain no token/private-key values.
 13. Negative test: target a repo without app installation and confirm explicit failure.

package/index.d.ts

@@ -1,11 +1,51 @@
 import type { JuniorPluginRegistration } from "@sentry/junior-plugin-api";
 
+export type GitHubAppPermissionLevel = "read" | "write" | "admin";
+
+/** Configure the built-in GitHub plugin manifest and hooks. */
 export interface GitHubPluginOptions {
+  /**
+   * Extra OAuth `scope` values to request during GitHub App user authorization.
+   *
+   * GitHub App user tokens report empty scopes, so Junior treats this as a
+   * local reauthorization contract only. Effective access still comes from the
+   * app permissions, installation repositories, and requesting user's access.
+   */
+  additionalUserScopes?: string[];
+
+  /**
+   * GitHub App installation permissions Junior should request for app tokens.
+   *
+   * Keys may use GitHub permission names with underscores or hyphens. Junior
+   * records these as plugin capabilities and requests read-only installation
+   * tokens by scoping read-capable permissions down to `read`.
+   * GitHub remains the source of truth for whether a permission exists.
+   */
+  appPermissions?: Record<string, GitHubAppPermissionLevel>;
+
+  /** Environment variable containing the GitHub App id. */
+  appIdEnv?: string;
+
+  /** Environment variable containing Junior's Git committer email. */
   botEmailEnv?: string;
+
+  /** Environment variable containing Junior's Git committer name. */
   botNameEnv?: string;
+
+  /** Environment variable containing the GitHub App OAuth client id. */
+  clientIdEnv?: string;
+
+  /** Environment variable containing the GitHub App OAuth client secret. */
+  clientSecretEnv?: string;
+
+  /** Environment variable containing the GitHub App installation id. */
+  installationIdEnv?: string;
+
+  /** Environment variable containing the GitHub App private key. */
+  privateKeyEnv?: string;
 }
 
-/** Register GitHub manifest content and trusted commit attribution hooks. */
+/** Register GitHub manifest content and runtime hooks. */
 export function githubPlugin(
   options?: GitHubPluginOptions,
 ): JuniorPluginRegistration;