# Git Provider Setup

This document covers manual setup for GitHub OAuth, Puter Git (Gitea), webhooks, and Convex environment variables.

> **Never place admin or user tokens in checked-in `.env` files or browser variables.** All secrets must be Convex environment variables set via `npx convex env set`.

## GitHub OAuth Application

1. Go to GitHub Settings > Developer settings > OAuth Apps > New OAuth App.
2. Set the application name (e.g., "Zopu").
3. Set the homepage URL to your `SITE_URL` (e.g., `https://zopu.cheaptricks.puter.wtf`).
4. Set the callback URL to `<SITE_URL>/api/auth/callback/github`.
5. Generate a client secret.
6. Set Convex environment variables:
   ```
   npx convex env set GITHUB_CLIENT_ID <your-client-id>
   npx convex env set GITHUB_CLIENT_SECRET <your-client-secret>
   ```

### Requested scopes

Zopu requests `repo` and `read:org`. The `repo` scope grants access to private repositories. `read:org` allows listing organization repositories.

## GitHub Webhook (manual setup for OAuth-based version)

1. Go to the GitHub repository Settings > Webhooks > Add webhook.
2. Payload URL: `<CONVEX_SITE_URL>/api/git/webhooks/github`
3. Content type: `application/json`
4. Secret: generate a strong random string and set it as:
   ```
   npx convex env set GITHUB_WEBHOOK_SECRET <your-webhook-secret>
   ```
5. Select individual events:
   - Push
   - Repository (created, deleted, transferred, renamed, visibility)
   - Delete
   - Create
   - Public
   - Fork
6. Do not select "Send me everything."

## Puter Git (Gitea) Admin Token

1. As a Gitea admin, go to Settings > Applications > Generate New Token.
2. Select scopes: `write:admin`, `write:organization`, `write:repository`.
3. Set the token:
   ```
   npx convex env set PUTER_GIT_ADMIN_TOKEN <your-admin-token>
   ```

This token is used only for platform administration (user creation, organization creation, repository creation, migration). It is never used for end-user operations.

## Puter Git Webhook

After a repository is created or migrated, Zopu ensures a webhook is configured automatically. If manual setup is needed:

1. Go to the Gitea repository Settings > Webhooks > Add Webhook > Gitea.
2. Target URL: `<CONVEX_SITE_URL>/api/git/webhooks/puter`
3. HTTP method: POST
4. Content-Type: `application/json`
5. Secret: generate a strong random string and set it as:
   ```
   npx convex env set GITEA_WEBHOOK_SECRET <your-webhook-secret>
   ```
6. Trigger on: Push events, Repository events.

## Credential Encryption Key

Generate a 32-byte encryption key for AES-GCM credential encryption:

```bash
openssl rand -base64 32 | base64 | tr -d '\n' | pbcopy
```

Set it as:

```
npx convex env set GIT_CREDENTIAL_ENCRYPTION_KEY <base64url-encoded-32-bytes>
```

The key must be exactly 32 bytes when base64url-decoded.

## Same-Origin Proxy for Better Auth Callbacks

Better Auth requires the callback URL to be on the same origin as `SITE_URL`. If your Convex deployment uses a different origin:

1. Configure a reverse proxy (e.g., Caddy) to forward `/api/auth/*` to the Convex deployment.
2. Set `SITE_URL` to the proxy origin.
3. Set `CONVEX_SITE_URL` to the Convex deployment URL.

## Validation Procedures

### Verify a Puter PAT connection

1. Connect a Puter PAT through the UI.
2. Verify the connection state shows `active`.
3. List private repositories to confirm token validity.

### Verify GitHub OAuth

1. Click "Connect GitHub" in the UI.
2. Complete the GitHub OAuth flow.
3. Verify the connection state shows `active`.

### Reconnection

If a token is expired or revoked:

1. The connection state shows `reauth-required`.
2. Reconnect the provider through the UI.
3. The old connection state is updated to `active`.
4. Projects, repositories, Work, and artifacts are not deleted.

## Environment Variables Summary

| Variable | Required | Description |
| --- | --- | --- |
| `SITE_URL` | Yes | Public-facing URL |
| `CONVEX_SITE_URL` | Yes | Convex deployment URL (may differ from SITE_URL with proxy) |
| `GIT_CREDENTIAL_ENCRYPTION_KEY` | Yes | Base64url-encoded 32-byte AES-GCM key |
| `PUTER_GIT_ADMIN_TOKEN` | Yes | Gitea admin token for provisioning |
| `GITHUB_CLIENT_ID` | For GitHub | OAuth app client ID |
| `GITHUB_CLIENT_SECRET` | For GitHub | OAuth app client secret |
| `GITHUB_WEBHOOK_SECRET` | For GitHub webhooks | HMAC verification secret |
| `GITEA_WEBHOOK_SECRET` | For Puter webhooks | HMAC verification secret |
| `FLUE_DB_TOKEN` | Yes | Private agent backend token |
| `FLUE_URL` | Optional | Private agent backend URL |
| `NATIVE_APP_URL` | Optional | Native app deep-link scheme |