# Provon Connectors

Connectors move 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 |
| 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](./gateway.md).

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

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

## Related Docs

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