# Repair Handoff

Repair handoff turns a reviewed Finding into a tracked work item in an issue tracker. Provon does
not edit the repository or apply patches; it creates a scoped issue and synchronizes the external
resolution status back to the Finding.

Supported issue trackers:

| Provider | Default destination fields | Resolution sync behavior                                                    |
| -------- | -------------------------- | --------------------------------------------------------------------------- |
| GitHub   | `owner`, `repo`            | Merged PR with successful checks or closed issue is recorded automatically. |
| GitLab   | project path               | Creates/updates issue; completion enters `awaiting_verification`.           |
| Linear   | `team`                     | Creates/updates issue; completion enters `awaiting_verification`.           |
| Jira     | `project`, `issueType`     | Creates/updates issue; completion enters `awaiting_verification`.           |

Configure the connector in **Connectors** before creating a work item. Only one primary work item
can exist for a Finding at a time.

## Configure GitHub

GitHub is the only provider that can automatically verify a merged pull request as the resolution.

### With OAuth

The deployment must provide:

```bash
GITHUB_INTEGRATION_CLIENT_ID=...
GITHUB_INTEGRATION_CLIENT_SECRET=...
```

Register this hosted callback:

```text
https://api.provon.dev/v1/integrations/github/callback
```

Then:

1. Open **Connectors** in the project.
2. Select **Connect** on GitHub.
3. Authorize the repository access.
4. Expand GitHub and set **Default owner** and **Default repo**.
5. Keep the connector enabled.

The default OAuth scope is `repo` because Provon must create and read Issues and inspect associated
pull requests, including in private repositories.

### With A Token

For local development or a deployment without OAuth:

1. Open **Connectors** and expand GitHub.
2. Enter a token that can create Issues and read pull requests in the target repository.
3. Set **Default owner** and **Default repo**.
4. Enable and save the connector.

Tokens may use the classic `ghp_...` or fine-grained `github_pat_...` form. Prefer the narrowest
repository access that still supports Issues and pull-request reads.

## Configure GitLab, Linear, And Jira

Each connector uses deployment-level OAuth credentials and project-level authorization. Register the
callback at:

```text
https://api.provon.dev/v1/integrations/<connector>/callback
```

Required environment variables:

| Connector | Required variables                                                 | Optional scope override     |
| --------- | ------------------------------------------------------------------ | --------------------------- |
| GitLab    | `GITLAB_INTEGRATION_CLIENT_ID`, `GITLAB_INTEGRATION_CLIENT_SECRET` | `GITLAB_INTEGRATION_SCOPES` |
| Linear    | `LINEAR_INTEGRATION_CLIENT_ID`, `LINEAR_INTEGRATION_CLIENT_SECRET` | `LINEAR_INTEGRATION_SCOPES` |
| Jira      | `JIRA_INTEGRATION_CLIENT_ID`, `JIRA_INTEGRATION_CLIENT_SECRET`     | `JIRA_INTEGRATION_SCOPES`   |

Set the default destination in the connector card so that work-item creation can omit explicit
`destination` fields.

## Create A Work Item

From the Workbench:

1. Expand a Finding.
2. Select **Confirm & create** if the Finding is unreviewed, or **Create work item** if it is
   already confirmed.
3. Provon creates the issue in the default repository and stores `github:owner/repo#number` on the
   Finding.

From the API:

```http
POST /v1/projects/:projectId/diagnostics/findings/:findingId/work-items
```

```json
{
  "provider": "github",
  "destination": {
    "owner": "provon",
    "repo": "provon"
  }
}
```

Omit `destination` to use the connector default.

## Issue Body

Each created issue contains:

```text
Goal
What is wrong
Cause assessment
Evidence
Verification
Provon correlation metadata
```

The hidden correlation metadata block includes the Finding ID and analysis revision so retries can
recover a remotely created issue after a local commit failure. Keep credentials and private payloads
out of issue bodies.

## Work Item Lifecycle

A work item progresses through states:

```text
provisioning -> planned -> in_progress -> done
              \-> canceled
```

Local sync state:

```text
pending -> synced
       \-> error
```

Actions available from the Workbench and API:

- **Sync**: manually pull the latest external status. Returns `updated`, `unchanged`, `failed`,
  `not_syncable`, or `not_current`.
- **Retry**: re-run creation for a failed provisioning attempt (`status: provisioning`,
  `externalId: null`, `syncState: error`).
- **Replace**: create a new work item, usually in a different provider or destination.
- **Abandon**: detach the local handoff without closing the external issue.

A Finding with an active work item (`provisioning`, `planned`, or `in_progress`) cannot be dismissed
or manually resolved. Mark the external work item done, sync, and then verify the Finding.

## Resolution Sync

- **GitHub**: a merged pull request linked to the issue or a closed issue is recorded as resolved
  automatically during sync.
- **GitLab, Linear, Jira**: the external issue reaching a done state moves the Finding to
  `awaiting_verification`. A user must then mark the Finding verified in Provon.

If a done work item is later reopened, the Finding becomes `regressed`.

## Access And Secrets

- Project API keys authenticate Gateway and OTLP clients; they are not connector credentials.
- Provider credentials and connector secrets are stored per project.
- Connector secrets are encrypted with the deployment integration secret.
- Disabling a connector pauses its use without deleting the stored configuration.
- Deleting a connector removes the project record and its stored secret.

Do not place provider keys, project API keys, or connector tokens in internal workflow definitions or
issue bodies.

## Evidence And Notification Connectors

This page covers issue-tracker repair handoff only. For trace evidence connectors such as Gateway or
OTLP, see [OpenTelemetry setup](../tracing/opentelemetry.md) and the
[AI Gateway overview](../ai-gateway/index.md). For connector management with the CLI, see
[Connectors CLI](../cli/connectors.md).