Skip to main content

​
Before you begin

Make sure you have:

​
Connect your GitHub account

1

Open Integrations

Go to Potpie → Settings → Integrations.
2

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:
​
1
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.
​
2
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.
​
3
CODE_PROVIDER_TOKEN — a single personal access token. Works across all provider types (GitHub, GitBucket, GitLab, Bitbucket).
​
4
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

​
GET /github/user-repos
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"
Query parameters
​
search
string
Filter repositories by name. Returns only repositories whose name contains the search string.
​
limit
integer
Maximum number of repositories to return in a single response.
​
offset
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.
1

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"
}
2

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"
3

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

​
User OAuth token
PostgreSQL
Encrypted at rest using Fernet symmetric encryption. Linked to your Potpie account on connection.
​
GitHub App private key
Environment variable
Stored in the GITHUB_PRIVATE_KEY environment variable on the server. Never exposed to clients.
​
Installation token
In-memory
Generated fresh per request and never persisted. Scoped to the specific installation.
​
GH_TOKEN_LIST
Environment variable
Stored in the GH_TOKEN_LIST env var. Tokens are rotated automatically across requests.
​
CODE_PROVIDER_TOKEN
Environment variable
Stored in the CODE_PROVIDER_TOKEN env var. Used as a single fallback when no other source resolves.