Repair Handoff

Supported issue trackers:

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:

GITHUB_INTEGRATION_CLIENT_ID=...
GITHUB_INTEGRATION_CLIENT_SECRET=...

Register this hosted callback:

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:

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

Required environment variables:

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:

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

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

Omit destination to use the connector default.

Issue Body#

Each created issue contains:

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:

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

Local sync state:

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 and the AI Gateway overview. For connector management with the CLI, see Connectors CLI.