Repair Handoff

Supported issue trackers:

Configure the issue tracker from the issue tracker menu on the Findings page 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. On the Findings page, open the issue tracker menu and choose GitHub.
2. Select Connect GitHub and authorize repository access.
3. In the same dialog, set Default owner and Default repo and save.

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. On the Findings page, open the issue tracker menu and choose GitHub.
2. Enter a token that can create Issues and read pull requests in the target repository.
3. Set Default owner and Default repo, then save.

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/handoffs

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

Omit destination to use the connector default. A successful start returns the enriched Finding view (with the new handoff and workItem) and confirms the Finding once the provider returns an external identity.

Handoff error responses#

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.

Handoff and Work Item Lifecycles#

Creation is tracked separately from the external resource:

FindingHandoff: pending -> completed
                        \-> failed -> pending (retry)

A FindingWorkItem is created only after the provider returns an external ID, key, and URL:

todo -> doing -> done
  \--------------> canceled

Work item sync status is independent:

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 the current failed handoff.
• Replace: start a new handoff that replaces the primary work item after successful creation.
• Abandon: stop tracking a failed handoff; no external work item exists yet.

A Finding with an active work item (todo, doing, or unknown) cannot be dismissed or manually resolved. Mark the external work item done, sync, and then verify the Finding.

Resolution Sync#

• GitHub: during sync, a merged pull request resolves the Finding (resolved) when its linked check runs all finish with conclusions success, neutral, or skipped, and none fail, time out, are cancelled, or are action required. A closed issue; a merged PR with failing or pending checks; a merged PR with no check runs; or a PR still open projects to awaiting_verification — closing or merging the external item alone is not proof of task-level improvement.
• 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.

A later occurrence after resolvedAt flips the Finding back to regressed; reopening a done work item during sync also rolls resolution backward rather than silently staying closed.

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 connector configuration fields or issue bodies.

Limitations#

• One primary work item per Finding; secondary references are tracked as history, not as parallel handoffs.
• Only GitHub carries automatic check-based verification; other providers always require explicit verification.
• Sync pulls external status; it never edits the tracker, forces a close, or applies a patch.
• Historical occurrences from before the handoff cannot retroactively verify a repair.

Other Integrations#

This page covers issue-tracker repair handoff only. For trace evidence integrations such as Gateway or OTLP, see OpenTelemetry setup and the AI Gateway overview. For scripted connector management, see Connectors CLI.