Sentry Integration
The Sentry project connector links error-tracking issues to AgentTeams plans as origin issues and editor context. The connection only supplies context. It does not create or run plans, send runner requests, or start any other automation.
Before connecting
- You need the Owner or Admin role for the team or project. Other members can view connection status, but cannot connect, reconnect, change the selected project, or disconnect it.
- An operator must register a Sentry Integration Platform app with the
org:read,project:read, andevent:readscopes. - Your organization must allow installation of the app and access to the intended project.
Connect a project
- In the web app, select a team and project, then open Project settings → Integrations.
- Select Connect Sentry on the Sentry card.
- Approve app access in the Sentry window. If the popup is blocked, allow popups in your browser and try again.
- After authentication, choose a Sentry organization and project, then select Save selection.
Only the selected Sentry project is used for search and issue linking in this AgentTeams project. To change it, select and save a different organization or project on the Integrations tab.
Link a Sentry issue to a plan
- Open Link origin issue on a plan detail page.
- Find the Sentry issue in search results. Check its title, issue identifier, and current status, then select it.
- The linked issue appears in the plan’s origin issue list with its Sentry link and status.
Sentry webhooks that pass signature verification update the state of origin issues that are already linked. This synchronization does not run the plan or a runner automatically.
Reconnect and disconnect
If a token expires or is revoked and Reconnect Sentry appears, reauthorize only Sentry. You do not need to sign out of AgentTeams. After reconnecting, select and save the organization and project again.
Disconnect removes the project’s stored Sentry authorization and stops new searches and status synchronization. Existing origin issue links remain on plans. Connect Sentry and select an organization and project to use it again.
Troubleshooting
| Symptom | What to check |
|---|---|
| The connect button is unavailable | Confirm that the current member is a team or project Owner/Admin. |
| The authentication window does not open | Allow browser popups and connect again. |
| Reconnect required | Keep the AgentTeams session and use Reconnect Sentry to renew only the Sentry authorization. |
| An organization or project is missing | Check app installation, the org:read, project:read, and event:read scopes, and your access to the organization. |
| Rate limit message | Wait and retry. If it continues, ask an operator to check the Sentry API limit. |
| Issue status does not update | Ask an operator to verify the Sentry webhook URL and signature secret. |
Operator checklist
Store connector settings only in the AgentTeams API/Railway service. The Web settings NEXT_PUBLIC_SENTRY_DSN, SENTRY_AUTH_TOKEN, SENTRY_ORG, and SENTRY_PROJECT are for browser monitoring and source-map uploads; they are not project connector credentials.
There is exactly one registration: a Public Integration on the Integration Platform. Account → API → Applications (OAuth Application) is a separate surface with no webhooks and no installations, so this connector does not use it.
- Redirect URL:
${API_URL}/api/auth/sentry/callback - Issue webhook:
${API_URL}/api/webhook/sentry - Permissions: Read on Organization, Project, and Issue & Event (
org:read,project:read,event:read) - Webhook subscriptions: Issues — Created, Resolved, Unresolved
- API-only settings:
SENTRY_INTEGRATION_ENABLED,SENTRY_CLIENT_ID,SENTRY_CLIENT_SECRET,SENTRY_APP_SLUG,SENTRY_APP_UUID,SENTRY_WEBHOOK_SECRET - All connector values above are required when
SENTRY_INTEGRATION_ENABLED=true. - Webhook signatures are generated with the integration’s Client Secret, so
SENTRY_WEBHOOK_SECRETis the same value asSENTRY_CLIENT_SECRET. - Verify Installation can stay enabled. AgentTeams confirms the installation right after it receives the token.
- Never put real client secrets, webhook secrets, or access tokens in the repository or Web environment variables.
For other project connections, see Project Settings and Connect a Repository.