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

## 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](../ai-gateway/index.md).

### 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](../tracing/opentelemetry.md).

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

## Related Docs

- [Findings](./index.md)
- [Quickstart](../get-started/quickstart.md)
- [Self-hosting configuration](../self-hosting/configuration.md)
- [Troubleshooting](../get-started/troubleshooting.md)