Skip to main content

​
Prerequisites

Before using the GitHub integration, you need:
  • A Potpie account
  • A GitHub account with access to the repositories you want to connect
  • Admin permissions on the repository or organization to install the GitHub App

​
Overview

The GitHub integration enables Potpie agents to interact with GitHub repositories through a GitHub App installation. The app provides secure, fine-grained access to code, pull requests, branches, and issues.

​
Quick Start

​
Prerequisites

  • GitHub account with repository access
  • Repository admin permissions (for app installation)
  • Potpie account

​
Setup Steps

1

Install Potpie GitHub App

Open Potpie GitHub App and click Install. Select repositories:
  • All repositories, or
  • Specific repositories only
2

Verify Installation

Parse a repository in Potpie to verify the connection:
  1. Go to New Chat
  2. Select the repository dropdown
  3. GitHub repos appear in the list
3

Start Using

Ask agents to interact with GitHub:“Show me the latest PR for repo owner/repo”“Create a branch called feature/new-auth”“Read the contents of src/auth.js”

​
Available Tools

The GitHub integration provides 6 tools. See GitHub Tools in the Tools Reference for full documentation.
ToolDescription
Issue FetcherFetch issues and pull requests
File ReaderRead file contents
Branch CreatorCreate branches
File CommitterModify and commit files
PR CreatorCreate pull requests
PR CommenterAdd PR comments

​
Self-Hosted Setup

For self-hosted Potpie instances, configure GitHub App credentials and authentication in addition to the cloud installation steps above.

​
Backend Configuration

Add these environment variables to your deployment: 
GITHUB_APP_ID=your_app_id
GITHUB_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----
CODE_PROVIDER_TOKEN=fallback_personal_access_token
CODE_PROVIDER_TOKEN_POOL=token1,token2,token3
  • GITHUB_PRIVATE_KEY — the raw PEM content of the private key generated in your GitHub App settings
  • CODE_PROVIDER_TOKEN — a personal access token used as a fallback for unauthenticated operations
  • CODE_PROVIDER_TOKEN_POOL — optional comma-separated list of tokens for distributing API rate limits

​
GitHub App Setup

​
Installation Process

  1. Navigate to App Installation
  2. Grant Permissions The Potpie GitHub App requests:
    • Read: Repository contents, pull requests, issues
    • Write: Pull requests, branches, commit status
    • Admin: Webhooks (optional)
  3. Select Repositories 
    ○ All repositories
● Only select repositories
  ☑ my-project
  ☑ backend-api
  ☐ private-repo
  4. Installation ID After installation, GitHub provides an installation ID. Potpie uses this to authenticate API calls.

​
Authentication Flow

​
Key Concepts

GitHub App vs OAuth App:
  • GitHub App: Installation-based, fine-grained permissions, app-level auth
  • OAuth App: User-based, broader permissions, user-level auth
Installation Token:
  • Short-lived (1 hour)
  • Generated from a JWT signed with the private key
  • Scoped to installed repositories only
JWT Creation: 
import jwt
import time

payload = {
    'iat': int(time.time()),
    'exp': int(time.time()) + 600,  # 10 minutes
    'iss': GITHUB_APP_ID
}

jwt_token = jwt.encode(payload, private_key, algorithm='RS256')

​
API Integration Details

JWT Generation: 
# 1. Create JWT
jwt_token = create_jwt(
    app_id=GITHUB_APP_ID,
    private_key=PRIVATE_KEY
)

# 2. Get installation token
response = requests.post(
    f"https://api.github.com/app/installations/{installation_id}/access_tokens",
    headers={"Authorization": f"Bearer {jwt_token}"}
)

installation_token = response.json()["token"]
API Calls: 
# Use installation token for API calls
headers = {
    "Authorization": f"Bearer {installation_token}",
    "Accept": "application/vnd.github.v3+json"
}

response = requests.get(
    "https://api.github.com/repos/owner/repo/pulls/123",
    headers=headers
)