GitHub Integration

Before you begin

Make sure you have:

Connect your GitHub account

Open Integrations

Go to Potpie → Settings → Integrations.

Authorize GitHub

Click Connect GitHub and complete the OAuth flow. Potpie stores your access token encrypted in PostgreSQL and links it to your account.

A GitHub account already connected to a different Potpie user cannot be merged or transferred.

How Potpie authenticates repository requests

Every repository request resolves authentication using the following priority order. Potpie tries each source in sequence and uses the first one that succeeds:

Highest priority

GitHub App installation token — used when a GitHub App is installed on the target organization or repository. A short-lived token is generated fresh per request and never stored.

GH_TOKEN_LIST — a comma-separated list of personal access tokens. One is picked at random per request to distribute load across GitHub rate limits. GitHub only.

CODE_PROVIDER_TOKEN — a single personal access token. Works across all provider types (GitHub, GitBucket, GitLab, Bitbucket).

Lowest priority

CODE_PROVIDER_USERNAME / CODE_PROVIDER_PASSWORD — basic auth, used only when no token source is available. Primarily for self-hosted GitBucket installs.

For local repositories, Potpie uses the filesystem path directly — no token resolution occurs.

List accessible repositories

endpoint

Returns all repositories accessible to the authenticated user.

curl http://localhost:8001/api/v2/github/user-repos \
  -H "x-api-key: YOUR_API_KEY"

import requests

response = requests.get(
    "http://localhost:8001/api/v2/github/user-repos",
    headers={"x-api-key": "YOUR_API_KEY"}
)

const response = await fetch("http://localhost:8001/api/v2/github/user-repos", {
  headers: { "x-api-key": "YOUR_API_KEY" }
});

Query parameters

string

Filter repositories by name. Returns only repositories whose name contains the search string.

integer

Maximum number of repositories to return in a single response.

integer

default:"0"

Number of results to skip. Use with limit to paginate through results.

Create a pull request from agent changes

PR creation happens through a conversation with the Code Generation Agent — not through a direct API call. You ask the agent to make code changes, then explicitly ask it to open a PR.

The agent only creates a PR when you explicitly ask for one. It will not open one automatically after making changes.

Start a conversation with the Code Generation Agent

POST /api/v2/conversations
Content-Type: application/json

{
  "project_id": "your_project_id",
  "agent_id": "code_generation_agent"
}

Request your code change

Send a message describing what you want changed. The agent will analyze the codebase and prepare the modification.

POST /api/v2/conversations/{conversation_id}/message
Content-Type: multipart/form-data

content: "Add input validation to the login function"

Ask the agent to create the PR

Once you’re happy with the proposed changes, ask the agent to open a pull request. Specify the branch name and title.

POST /api/v2/conversations/{conversation_id}/message
Content-Type: multipart/form-data

content: "Create a PR for these changes on branch fix/login-validation with title 'Fix: add login input validation'"

The response streams back and includes the PR URL when complete:

PR created: https://github.com/owner/repo/pull/42
Branch: fix/login-validation
Commit: a3f9c12

How tokens are stored

PostgreSQL

Encrypted at rest using Fernet symmetric encryption. Linked to your Potpie account on connection.

Environment variable

Stored in the GITHUB_PRIVATE_KEY environment variable on the server. Never exposed to clients.

In-memory

Generated fresh per request and never persisted. Scoped to the specific installation.

Environment variable

Stored in the GH_TOKEN_LIST env var. Tokens are rotated automatically across requests.

Environment variable

Stored in the CODE_PROVIDER_TOKEN env var. Used as a single fallback when no other source resolves.

Get Started

Concepts

Tutorials

Modes

Platform

Developer

Example Uses

GitHub Integration

Before you begin

Connect your GitHub account

How Potpie authenticates repository requests

List accessible repositories

Create a pull request from agent changes

How tokens are stored

​Before you begin

​Connect your GitHub account

​How Potpie authenticates repository requests

​List accessible repositories

​Create a pull request from agent changes

​How tokens are stored

Before you begin

Connect your GitHub account

How Potpie authenticates repository requests

List accessible repositories

Create a pull request from agent changes

How tokens are stored