> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fix a Sentry issue

> 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 theme={null}
   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 theme={null}
   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 theme={null}
   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.