Skip to content

Provon Connectors

Connectors move 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.
On this page Browse sections

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
Automation issue systems GitHub, GitLab, Linear, Jira Let workflow steps open or update tracked work
Automation notifications Slack, Microsoft Teams, Lark, email Send review and operations updates
Automation data destinations Notion, Lark Base, monday.com, Airtable Write structured workflow records
Blob export S3, Azure Blob, Google Cloud Storage, custom object storage Archive workflow artifacts

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 callback, replacing the origin with the public Provon URL:

text
https://your-provon.example.com/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
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 OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:3000"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $PROVON_API_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

See OpenTelemetry setup.

Automation Connectors#

The Connectors page groups automation 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.

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://your-provon.example.com/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 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. Trigger an Automation from a Finding or evaluation result.
  2. Format a compact review message.
  3. Send it to Slack, Teams, Lark, or email.
  4. Keep the Finding as the evidence source of truth.

Structured Archive#

  1. Select the workflow 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.