Sentry Plugin

Use the Sentry plugin to investigate issues with a user’s Sentry account, make requested project, team, and alert changes, and respond to new issues and metric alerts through watches and event automations.

Junior stores each user’s OAuth grant and uses it only for that user’s requests. Optional org read access lets Junior read Sentry data without a user’s OAuth token, such as in scheduled tasks and event automations. Webhooks use a separate internal integration.

Install

pnpm add @sentry/junior @sentry/junior-sentry

plugins.ts

import { defineJuniorPlugins } from "@sentry/junior";
import { sentryPlugin } from "@sentry/junior-sentry";

export const plugins = defineJuniorPlugins([sentryPlugin()]);

Register sentryPlugin() so Junior loads the webhook route.

Config

Set conversation config with jr-rpc config set, or define the same keys for every conversation with createApp({ configDefaults }). Set deployment variables in the Junior environment, then redeploy. Explicit values in a request always win over conversation defaults.

Conversation defaults

sentry.org

Default Sentry organization slug when a request does not name one.

• Define: jr-rpc config set sentry.org <organization>
• Install-wide default: configDefaults["sentry.org"]
• Required: No
• Environment override: None

sentry.project

Default Sentry project slug when a request does not name one.

• Define: jr-rpc config set sentry.project <project>
• Install-wide default: configDefaults["sentry.project"]
• Required: No
• Environment override: None

Environment variables

SENTRY_CLIENT_ID

OAuth client ID used when a user connects their Sentry account.

• Define: Set SENTRY_CLIENT_ID in the deployment environment
• Required: Yes for user OAuth
• Environment override: SENTRY_CLIENT_ID

SENTRY_CLIENT_SECRET

OAuth client secret used when a user connects their Sentry account.

• Define: Set SENTRY_CLIENT_SECRET in the deployment environment
• Required: Yes for user OAuth
• Environment override: SENTRY_CLIENT_SECRET

SENTRY_READ_TOKEN

Internal integration token with read-only scopes. Junior uses it for Sentry API reads.

• Define: Set SENTRY_READ_TOKEN in the deployment environment
• Required: Yes for org read access; otherwise no
• Environment override: SENTRY_READ_TOKEN

SENTRY_WEBHOOK_ORG

Organization slug allowed to send webhooks.

• Define: Set SENTRY_WEBHOOK_ORG in the deployment environment
• Required: Yes for events; otherwise no
• Environment override: SENTRY_WEBHOOK_ORG

SENTRY_WEBHOOK_SECRET

Internal integration client secret used to verify webhooks.

• Define: Set SENTRY_WEBHOOK_SECRET in the deployment environment
• Required: Yes for events; otherwise no
• Environment override: SENTRY_WEBHOOK_SECRET

Set up user OAuth

Create a Sentry OAuth app with this redirect URL:

<base-url>/api/oauth/callback/sentry

Set SENTRY_CLIENT_ID and SENTRY_CLIENT_SECRET to the app’s credentials. Junior requests these scopes:

alerts:write event:write member:read org:read project:releases project:write team:write

Reconnect after scope changes. Existing grants do not pick up new scopes automatically.

With these scopes, Junior can make Sentry writes that a user asks for, such as creating projects, changing project settings, managing teams, and managing alerts. The user’s own Sentry role still applies. The skill does not limit which requests Junior makes. To limit access, narrow the OAuth scopes or add host egress rules.

Set up org read access

Without org read access, every Sentry request needs the requesting user’s OAuth token. Scheduled tasks, event automations, and messages from other bots cannot send an authorization link, so their Sentry requests fail.

Use a separate Sentry internal integration from the webhook integration, so you can revoke it on its own.

1. Create an internal integration in the organization.
2. Grant read-only permissions for Project, Issue & Event, Organization, and Release.
3. Create a token for the integration.
4. Set SENTRY_READ_TOKEN to the token.
5. Redeploy Junior.

Junior uses the token for GET, HEAD, and OPTIONS requests to the Sentry API. This includes Explore queries for spans, logs, and traces. Sentry limits the token to the organization that installed the integration. Writes and /api/0/users/ requests use the requesting user’s OAuth token.

Anyone who can talk to Junior can read every project the token can read. Sentry audit logs show the integration, not the Slack user.

Set up issue webhooks

Create a Sentry internal integration in the organization that should send issue webhooks. A public Sentry app is not required.

1. Create an internal integration.
2. Enable the issue webhook resource.
3. Set the webhook URL to:

https://<junior-host>/api/webhooks/sentry

4. Set SENTRY_WEBHOOK_ORG to the organization slug.
5. Set SENTRY_WEBHOOK_SECRET to the integration’s client secret.
6. Redeploy Junior.

Junior verifies each webhook signature and accepts webhooks only from the configured organization.

Metric alert webhooks

Sentry sends metric alerts only to an integration that is an action on the alert.

1. In the same internal integration, enable Alert Rule Action.
2. On each metric alert that Junior should receive, add this trigger action:

{
  "type": "sentry_app",
  "sentryAppId": <integration-id>,
  "targetType": "sentry_app",
  "targetIdentifier": <integration-id>
}

Watches

Set SENTRY_WEBHOOK_ORG and SENTRY_WEBHOOK_SECRET to enable watches. See Watches for the difference between temporary watches and durable event automations.

issue

Subscribe to one issue with org/project#issueId.

issue.created

The issue was created.

project

Subscribe to all new issues in a project with org/project.

issue.created

An issue was created in the project.

metric_alert

Subscribe to one metric alert with metric-alert:org/alertRuleId.

metric_alert.critical

The alert reached its critical threshold.

metric_alert.warning

The alert reached its warning threshold.

metric_alert.resolved

The alert resolved.

Junior publishes each state once for each alert incident.

Create the watch or event automation before the webhook arrives. Junior does not replay earlier webhooks.

Verify

OAuth: Connect Sentry from Slack, then query an issue or organization.

Org read access: Ask Junior to read an issue from a scheduled task, then make sure it does not ask you to connect Sentry.

Webhooks: Subscribe to a project, then create a test issue in that project. For metric alerts, subscribe to the alert, then lower its threshold until it triggers.

Security

• Junior stores user tokens and does not include them in model input.
• The org read token is used only for read requests. Writes always need the requesting user’s OAuth token.
• Webhooks use the internal integration client secret, not user OAuth.
• Missing or stale user authorization starts a private reconnect flow.

Failure modes

• OAuth callback fails: Set the app’s redirect URL to exactly <base-url>/api/oauth/callback/sentry.
• Sentry returns 401: Reconnect Sentry to replace the stale or revoked token.
• Sentry reports a missing scope: Reconnect Sentry to grant the current scopes.
• Sentry returns 403: Connect an account with access to the requested organization and project. With org read access, also check the integration’s read permissions.
• A scheduled task cannot read Sentry: Set SENTRY_READ_TOKEN. Confirm the request targets the organization that installed the integration.
• Webhooks are ignored: Check SENTRY_WEBHOOK_ORG and SENTRY_WEBHOOK_SECRET, then confirm a matching watch or event automation exists. For metric alerts, also confirm the integration is a trigger action on the alert.
• Authorization links use the wrong host: Set JUNIOR_BASE_URL to Junior’s public URL.

Next step

Review Watches and Security Hardening.