The GitHub integration gives agents access to GitHub repositories and APIs. Today you connect GitHub with a **personal access token (PAT)** through the `dvx` CLI. The platform also supports a **GitHub App** mode (short-lived installation tokens, private key held by the enclave), but App mode isn't configurable via the CLI yet - see the note below.

## Personal Access Token Mode

Use this when you want a simple, direct credential.

### Step 1: Create a GitHub PAT

1. In GitHub, go to **Settings > Developer settings > Personal access tokens > Fine-grained tokens** (recommended) or **Tokens (classic)**
2. Create a token with the required permissions:
   - For fine-grained tokens: select the repositories and permissions the agent needs
   - For classic tokens: select scopes like `repo`, `read:org`, etc.
3. Set an expiry and click **Generate token**
4. Copy the token (`ghp_...` or `github_pat_...`)

### Step 2: Link to the Agent

```bash
# With --pat flag
dvx agent integration github link <agent> --pat ghp_...

# Interactive prompt (token hidden)
dvx agent integration github link <agent>

# Piped from stdin
echo "ghp_..." | dvx agent integration github link <agent>
```

Daevix validates the token by calling GitHub's `/user` endpoint, then stores it encrypted as the `github:token` agent secret.

## GitHub App mode (platform capability)

> **Not yet configurable via the CLI.** GitHub App mode is supported by the platform but can't currently be set up with `dvx` - PAT mode is the supported Stage-1 path. This note describes what App mode offers for when CLI support lands.

In App mode the platform stores the App's private key (held by the enclave, never delivered to the agent) and mints a short-lived installation token (1-hour lifetime) on demand: it signs a GitHub App JWT with the private key, exchanges it for an installation access token, and returns that to the agent. This gives scoped, auto-rotating tokens that aren't tied to a user account. If an agent is compromised, the attacker only ever gets a token that expires within the hour.

## How Agents Use GitHub Credentials

Once linked, agents access their GitHub token through the enclave's credentials API:

```bash
# Using the dvxir CLI
dvxir credentials list
# Output: github    pat    octocat        (PAT mode)
# Output: github    app    my-github-app  (App mode)

dvxir credentials get github
# Output: ghp_... (PAT) or ghs_... (installation token)
```

For GitHub App integrations, the token returned is a short-lived installation token (1-hour lifetime). The agent should re-fetch it when needed rather than caching it long-term.

Agents typically use the token for Git operations or GitHub API calls:

```bash
# Git clone with token
git clone https://x-access-token:$(dvxir credentials get github)@github.com/org/repo.git

# GitHub API call
curl -H "Authorization: Bearer $(dvxir credentials get github)" \
  https://api.github.com/repos/org/repo
```

## Unlinking

Unlinking removes the integration, its encrypted secrets (token or private key), and any associated configuration in a single transaction.

```bash
dvx agent integration github unlink <agent>
```

Unlike GitLab's automated mode, there is no deprovisioning step for GitHub - the PAT or App credentials are simply deleted from Daevix. The GitHub App itself remains installed and can be reused for other agents.

## Troubleshooting

### "Invalid GitHub personal access token" on link

The token failed validation against GitHub's `/user` endpoint. Verify:
- The token is correct (starts with `ghp_` or `github_pat_`)
- The token hasn't expired or been revoked
- The token has at least read access to the user's profile

### Agent gets 401 errors when using the token

The token may have expired or been revoked. Unlink and re-link with a fresh token (`dvx agent integration github unlink <agent>`, then link again).