GitHub Plugin
The GitHub plugin uses a GitHub App so Junior can read repositories with installation tokens and create or update GitHub issues and pull requests with user-to-server tokens attributed to the requesting GitHub user with the app badge.
Install
Section titled “Install”Install the plugin package alongside @sentry/junior:
pnpm add @sentry/junior @sentry/junior-githubRuntime setup
Section titled “Runtime setup”Add the GitHub plugin factory to the plugin set exported from plugins.ts. The factory registers the GitHub manifest,
bundled skills, and Git commit attribution hooks together.
import { defineJuniorPlugins } from "@sentry/junior";import { githubPlugin } from "@sentry/junior-github";
export const plugins = defineJuniorPlugins([ githubPlugin({ botNameEnv: "GITHUB_APP_BOT_NAME", botEmailEnv: "GITHUB_APP_BOT_EMAIL", }),]);Configure environment variables
Section titled “Configure environment variables”Set these values in the host environment:
| Variable | Required | Purpose |
|---|---|---|
GITHUB_APP_ID | Yes | GitHub App identity. |
GITHUB_APP_CLIENT_ID | Yes | GitHub App OAuth client id for user-token auth. |
GITHUB_APP_CLIENT_SECRET | Yes | GitHub App OAuth client secret for user-token auth. |
GITHUB_APP_PRIVATE_KEY | Yes | GitHub App signing key. |
GITHUB_INSTALLATION_ID | Yes | Repository or organization installation target. |
GITHUB_APP_BOT_NAME | Yes | Git author name, for example <app-slug>[bot]. |
GITHUB_APP_BOT_EMAIL | Yes | Git author noreply email for the App bot user. |
GITHUB_INSTALLATION_ID selects the GitHub App installation for the deployment.
GITHUB_APP_BOT_EMAIL uses the GitHub noreply format
<bot-user-id>+<app-slug>[bot]@users.noreply.github.com. Get the bot user id
from https://api.github.com/users/<app-slug>%5Bbot%5D.
Vercel example:
vercel env add GITHUB_APP_ID productionvercel env add GITHUB_APP_CLIENT_ID productionvercel env add GITHUB_APP_CLIENT_SECRET productionvercel env add GITHUB_INSTALLATION_ID productionvercel env add GITHUB_APP_BOT_NAME productionvercel env add GITHUB_APP_BOT_EMAIL productionvercel env add GITHUB_APP_PRIVATE_KEY production --sensitive < ./github-app-private-key.pemCreate the GitHub App
Section titled “Create the GitHub App”Create and install a GitHub App before you verify GitHub workflows:
- Open GitHub App settings and create a new app.
- Generate a private key and store the downloaded
.pemfile securely. - Grant repository permissions for:
- Actions: Read and write
- Issues: Read and write
- Contents: Read and write
- Pull requests: Read and write
- Workflows: Write
- Metadata: Read
- Install the app on the repository or organization Junior should access.
- Copy the App ID, OAuth client ID/secret, installation ID, bot name, and bot noreply email into your deployment environment.
If your team works across multiple repositories, have users include owner/repo in their GitHub request whenever the target is not obvious from the conversation.
That only helps when those repositories are covered by the same GitHub App installation ID.
Verify
Section titled “Verify”Run a real GitHub workflow in the chat surface where people will use it:
Create a GitHub issue in owner/repo titled "Junior GitHub plugin check" with body "Verification run"Then confirm:
- The issue is created in the expected repository.
- The author is the requesting GitHub user with the GitHub App badge.
- A follow-up GitHub request can update or comment on the same issue without asking the user to handle tokens manually after authorization.
- A pushed branch can be turned into a draft PR when Junior uses explicit repo targeting and
--headduringgh pr create.
For code changes, a local git commit does not call GitHub. The GitHub write happens when Junior pushes the branch or writes Git objects through the REST API. Those operations require Contents: write on the target repository and write access for the requesting GitHub user. If the commit changes workflow files under .github/workflows, expect Workflows: write as well. Creating the PR after the branch exists is a separate pull-request write operation.
Security model
Section titled “Security model”- Junior mints GitHub App installation and user-to-server tokens on the host, not in the sandbox.
- When the GitHub skill runs authenticated
ghorgitcommands, sandbox traffic toapi.github.comandgithub.comis forwarded through Junior for host-side auth. - App-readable requests use GitHub App installation tokens. GitHub account identity checks and write requests require the requester to authorize the GitHub App, then use that user’s GitHub App user-to-server token.
- The GitHub App installation determines which repositories are reachable. Repo context guides command flags; it does not narrow issued credentials.
- The host-side lease is bounded by the sandbox session and token expiry. It is not exposed as reusable long-lived auth inside the sandbox.
- Capability scoping is mainly an accident-prevention layer: it keeps routine issue, contents, and pull-request workflows from minting broader write access than they need.
- It is not a full containment boundary. The agent can still request broader GitHub capabilities when a task genuinely needs them, so operators should treat GitHub App installation scope as the real trust boundary.
Failure modes
Section titled “Failure modes”Access deniedfrom GitHub: the app is not installed on the target repository or organization. Install the app on that target, then retry.Bad credentialsor signing errors:GITHUB_APP_PRIVATE_KEYdoes not match the App ID. Upload the private key generated for the same app asGITHUB_APP_ID.- Missing repository context: Junior could not determine which repository to use. Include
owner/repodirectly in the GitHub request, or configure a default GitHub repository for that thread, and retry. - Permission-style failures during issue or pull request workflows: the GitHub App lacks the required permission or installation scope. Update the app permissions or install target, then retry.
- Fork creation failures: GitHub requires
Administration: writeandContents: read, plus app installation on both source and destination accounts. Routine PR creation should push a branch explicitly and usegh pr create --headinstead of creating a fork.
Next step
Section titled “Next step”Read Plugin Auth & Context for the public auth and target-context model.