Skip to content

Repair Handoff And Connectors

Connectors move Finding evidence and review state across the Provon boundary. They are project-scoped and store credentials as encrypted secrets.

View as Markdown Open the plain-text version of this page.

Connector Roles#

Role Supported paths Purpose
Evidence input OpenAI-compatible Gateway, OpenTelemetry/OTLP Capture model and agent behavior
Finding repair handoff GitHub Create repair Issues and track external resolution
Issue-system handoff GitHub, GitLab, Linear, Jira Create or update tracked work from Findings
Notifications Slack, Microsoft Teams, Lark Forward Finding review and operations updates
Data destinations Notion, Lark Base, monday.com, Airtable Write structured records from internal workflows

The distinction matters: GitHub is currently the only connector used by the canonical Finding repair handoff and status sync. Configuring another issue-system connector does not make it a Finding repair-status provider.

GitHub Repair Handoff#

Use GitHub when a Finding should become repair work for Claude Code, Codex, or another controlled coding-agent workflow.

Configure 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.

Configure 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.

Repair Issue Contract#

Selecting Create repair issue on a Finding:

  1. creates an Issue in the default repository;
  2. adds the provon-repair label;
  3. stores github:owner/repo#number on the Finding;
  4. changes the Finding review state to confirmed;
  5. starts external status tracking.

The Issue includes the goal, diagnosis, evidence, remediation direction, delivery requirement, and hidden correlation metadata. Provon records a merged pull request or closed Issue as resolved.

Evidence Connectors#

Gateway#

Use the Gateway when the application already speaks an OpenAI-compatible API and Provon should own routing, policy, guardrails, and trace capture.

text
https://gateway.provon.dev/v1

For local development, use http://127.0.0.1:3000/gateway/v1.

See Gateway.

OpenTelemetry#

Use OTLP/HTTP when the application already emits telemetry or must keep calling providers directly.

bash
export PROVON_OTEL_URL="https://otel.provon.dev/v1"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="$PROVON_OTEL_URL/traces"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $PROVON_API_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

For local development, set PROVON_OTEL_URL to http://127.0.0.1:3000/v1.

See OpenTelemetry setup.

Connector Destinations#

The Connectors page groups destinations by intent:

  • Handoff: GitHub, GitLab, Linear, and Jira.
  • Notify: Slack, Microsoft Teams, and Lark.
  • Data: Notion, Lark Base, monday.com, and Airtable.

OAuth-backed connectors use deployment-level client credentials and project-level authorization. Webhook and token connectors can be configured directly in the project.

Data destinations are used by internal platform workflows and are not a user-facing automation surface.

OAuth Environment Variables#

Connector Required variables Optional scope override
GitHub GITHUB_INTEGRATION_CLIENT_ID, GITHUB_INTEGRATION_CLIENT_SECRET GITHUB_INTEGRATION_SCOPES
Slack SLACK_INTEGRATION_CLIENT_ID, SLACK_INTEGRATION_CLIENT_SECRET SLACK_INTEGRATION_SCOPES
Notion NOTION_INTEGRATION_CLIENT_ID, NOTION_INTEGRATION_CLIENT_SECRET None
Jira JIRA_INTEGRATION_CLIENT_ID, JIRA_INTEGRATION_CLIENT_SECRET JIRA_INTEGRATION_SCOPES
Linear LINEAR_INTEGRATION_CLIENT_ID, LINEAR_INTEGRATION_CLIENT_SECRET LINEAR_INTEGRATION_SCOPES

Callback paths follow:

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

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.

Common Patterns#

Trace To Repair#

  1. Capture an agent conversation through Gateway or OTLP.
  2. Let diagnostic Rules publish a supported Finding.
  3. Review the cause and evidence.
  4. Create a GitHub repair Issue.
  5. Let a user-controlled coding agent open a pull request.
  6. Track the external resolution on the Finding.

Finding Notification#

  1. Configure a notification connector such as Slack, Teams, or Lark.
  2. Forward compact review messages from Finding review events.
  3. Keep the Finding as the evidence source of truth.

Structured Archive#

  1. Select the Finding or record to export.
  2. Map fields to Notion, Lark Base, monday.com, or Airtable.
  3. Store Provon IDs and evidence references with the external record.
  4. Treat the external table as a destination, not the canonical Finding store.