tracer-cloud--opensre/docs/fix-sentry-issue.mdx

---
title: "Fix a Sentry issue"
description: "Paste a Sentry issue URL and have the Pi coding agent propose a fix — as a reviewable diff or a pull request."
---

The **Sentry issue-fix tool** lets you point OpenSRE at a [Sentry](https://sentry.io) issue and
have the [Pi](https://pi.dev) coding agent propose a fix. OpenSRE fetches the issue context,
runs Pi in your current repository, and returns a summary plus the git diff.

By default it **only edits the working tree** so you can review the diff. When you ask it to
`open_pr` (and enable the ship switch), it also commits the fix to a fresh branch, pushes it,
and opens a **pull request** — it **never pushes to your base/`main` branch**.

<Warning>
This is a **mutating** tool — it changes files on disk and can open a PR. It is **disabled by
default**: the fix step needs `PI_ISSUE_FIX_ENABLED=1`, Sentry configured, and the Pi CLI
installed. Opening a PR needs a **second** switch, `PI_ISSUE_FIX_SHIP_ENABLED=1`, plus a GitHub
token. Enable each deliberately.
</Warning>

## Quick reference

| Env var | What it does |
| --- | --- |
| `PI_ISSUE_FIX_ENABLED` | Opt-in switch for the fix step. Set to `1` to enable. Off by default. |
| `PI_ISSUE_FIX_SHIP_ENABLED` | Second opt-in required to open a PR (`open_pr`). Off by default. |
| `GITHUB_TOKEN` / `GH_TOKEN` | GitHub token used to open the pull request (needs `repo`/`pull_request` write). |
| `SENTRY_ORG_SLUG` / `SENTRY_AUTH_TOKEN` | Sentry org + token used to fetch the issue (`SENTRY_URL` for self-hosted). |
| `PI_CODING_MODEL` | Pi model used for the fix (shared with the Pi coding tool). |
| `PI_CODING_WORKSPACE` | Repository Pi edits. Defaults to the current directory. |
| `PI_CODING_TIMEOUT_SECONDS` | Per-run timeout (default 600, clamped 60–1800). |

| Parameter | What it does |
| --- | --- |
| `sentry_url` | The Sentry issue URL to fix (required). |
| `open_pr` | When `true`, commit the fix to a fresh branch and open a PR. Defaults to `false` (diff only). |

## Enable it

1. Configure Sentry (org + token) and install/authenticate the Pi CLI:
   ```bash
   export SENTRY_ORG_SLUG=your-org
   export SENTRY_AUTH_TOKEN=...           # token with issue read access
   npm i -g @earendil-works/pi-coding-agent
   ```
2. Turn the tool on:
   ```bash
   export PI_ISSUE_FIX_ENABLED=1
   export PI_CODING_MODEL=anthropic/claude-haiku-4-5   # optional
   ```
3. (Optional) Let OpenSRE open the fix as a pull request:
   ```bash
   export PI_ISSUE_FIX_SHIP_ENABLED=1
   export GITHUB_TOKEN=...        # token with PR-create access to the repo
   ```

## Using it from the interactive shell

Once enabled, just ask in plain language in `opensre` — the action agent recognizes the intent
and runs the tool:

```
fix this sentry issue https://your-org.sentry.io/issues/12345/ and open a pull request
```

Say "open a pull request" (or "ship it") to open a PR; leave it out to only get the diff. Use a
*fix* verb — "investigate"/"diagnose" routes to the read-only investigation pipeline instead.

## How it works

1. You paste a Sentry issue URL (e.g. `https://your-org.sentry.io/issues/12345/`) and ask
   OpenSRE to fix it.
2. OpenSRE resolves the issue from Sentry and builds a short, **masked** task (title, error,
   culprit, location) — your Sentry token is never sent to Pi.
3. Pi edits the current repository to implement the fix.
4. You get back `success`, a `summary`, `changed_files`, and the `diff` to review.
5. If you asked for `open_pr` (and shipping is enabled), OpenSRE commits the change to a fresh
   `opensre/sentry-fix-<id>-<sha>` branch, pushes it, opens a PR into your base branch, and
   returns the `branch_name`, `pr_url`, and `pr_number`.

## Opening a pull request

Ask OpenSRE to *fix the issue and open a PR*. The fix always lands on a new namespaced branch and
is proposed via PR:

- OpenSRE **never** commits to or pushes your base/`main` branch, and never force-pushes.
- The PR is opened **into** the repo's default branch from the new branch, with a body linking the
  Sentry issue and listing the changed files.
- If the fix succeeds but the PR can't be opened (e.g. missing token, push rejected), you still get
  the `diff` and `changed_files` back, plus the `error_kind`, so you can ship it manually.

## Supported URLs

- `https://<org>.sentry.io/issues/<id>/`
- `https://sentry.io/organizations/<org>/issues/<id>/`
- self-hosted `https://sentry.<company>.com/organizations/<org>/issues/<id>/`

## Notes

- Without `open_pr`, nothing is committed or pushed; you review the diff and decide what to do.
- If the tool is disabled, the URL is unsupported, Sentry is unconfigured, Pi is missing, or a PR
  can't be opened, it returns a clear `error_kind` instead of silently doing the wrong thing.