# Integrations

Integrations give an agent an identity in an external service - most often a GitHub or GitLab account it can act as. Every integration follows the same lifecycle: **link**, the platform delivers the credential to the agent, and **unlink**. This page explains how they work; for the commands, see [Use integrations from the CLI](/cli-integrations/).

## Two levels

### Level 1: per-agent integrations

Every integration is scoped to a single agent - there's no shared credential used by multiple agents. Depending on the mode, the credential is either:

- **Operator-provided** - a PAT or GitHub App private key you supply when linking, or
- **Platform-provisioned** - minted automatically by a credential provider (Level 2).

Either way the credential is stored encrypted and is **never exposed to the agent directly**. Agents retrieve credentials through the enclave's credentials API, which is the chokepoint for auditing, revocation, and (for GitHub Apps) on-demand token minting.

### Level 2: org-level credential providers

A credential provider is an org-level resource that automates Level 1 provisioning. It holds one privileged identity in the target platform - for example a GitLab token with Owner access to a group - and uses it to **mint a dedicated, scoped identity per agent** on demand. Register it once; from then on, linking an agent mints a fresh identity, and unlinking deprovisions it.

Think of it as an identity vending machine: one privileged credential in, many scoped credentials out - no shared token across agents. Credential providers currently support **GitLab**, in two modes: service account (works on the GitLab.com free tier) and project access token. See [Credential Providers](/gitlab-integration/#credential-providers).

## Integration types

| Category | Providers | Purpose |
|----------|-----------|---------|
| **Integrations** | GitHub, GitLab | Source-code access and identity provisioning |
| **Channels** | Telegram | A way to message the agent |

An agent can have **at most one active integration per provider**. (Telegram is a *channel*, not an integration - see [Configure your agent](/configure-agent/).)

## How linking works

When you link an integration (`dvx agent integration …`), the platform:

1. **Validates** the credential against the external service's API.
2. **Encrypts** it with AES-256-GCM envelope encryption.
3. **Stores** it as an agent secret (`github:token`, `gitlab:token`, …) marked not agent-accessible.
4. **Records** an integration with metadata (username, auth type, external IDs).

Because the secret is marked not agent-accessible, the agent can't read it through the secrets path - it must go through the enclave's credentials endpoint, which lets the platform control how and when the credential is delivered. For PAT integrations the stored token is returned directly; for GitHub Apps the enclave holds the private key and mints a short-lived (1-hour) installation token, so the agent never sees the key.

Unlinking removes the integration, its secrets, and any associated config in one transaction - and, for automated GitLab integrations, deprovisions the identity in GitLab (best-effort).

## Authentication modes

### Personal access token (PAT)

The simplest mode: you provide a token, the platform validates and stores it. Available for GitHub and GitLab. Simple and works on all tiers, but the token is tied to a user account and rotates manually.

### GitHub App

GitHub-specific. Instead of a static token, the platform stores the app's private key and mints short-lived installation tokens on demand. Scoped permissions, automatic rotation, not tied to a user - at the cost of creating and installing a GitHub App.

### Automated (credential provider)

GitLab-specific. The platform uses a [credential provider](/gitlab-integration/#credential-providers) to provision a dedicated GitLab identity per agent - isolated per-agent identities with automatic provisioning and deprovisioning, at the cost of a provider with Owner access to a GitLab group.

See [GitLab Integration](/gitlab-integration/) for the full GitLab guide and [GitHub Integration](/github-integration/) for GitHub.

## Managing integrations

Operators manage integrations with the `dvx` CLI:

```bash
dvx agent integration list <agent>
dvx agent integration gitlab link <agent> --pat <token>
dvx agent integration github link <agent> --pat <token>
dvx agent integration gitlab unlink <agent>
```

Tokens can be passed with `--pat`, piped from stdin, or entered interactively. See [Use integrations from the CLI](/cli-integrations/) for the full workflow, including credential providers.

## Secret naming convention

Integration secrets follow the `provider:key` pattern:

| Secret name | Created by | Description |
|-------------|------------|-------------|
| `github:token` | GitHub PAT integration | GitHub personal access token |
| `github:private_key` | GitHub App integration | GitHub App private key (PEM) |
| `gitlab:token` | GitLab integration (PAT or automated) | GitLab access token |
| `telegram:bot_token` | Telegram channel | Telegram bot token |
| `telegram:allowed_users` | Operator | Comma-separated Telegram user IDs |
| `llmproxy:llm.api_key` | Operator | Org-level LLM API key for the proxy |
| `agent:llmproxy.llm.api_key` | Operator | Per-agent LLM API key (overrides org-level) |

All integration secrets are stored not-agent-accessible - agents reach them through the credentials API, not the secrets API.