github-app-integration.mdx

title	description
GitHub App Integration	Connect Pullbase to private Git repositories using a GitHub App.

Pullbase supports GitHub Apps to securely access private repositories without embedding personal access tokens.

When to use a GitHub App

• Your configuration repository is private.
• You need auditable, revokable permissions scoped to specific repositories.
• You want Pullbase to fetch short-lived installation tokens on behalf of agents.

You can start with public repositories (set `PULLBASE_GIT_ENABLED=false`). Add a GitHub App once you move configuration to a private repository.

Create the GitHub App

1. Visit [https://github.com/settings/apps/new](https://github.com/settings/apps/new) (or the equivalent GitHub Enterprise URL). 2. Provide a descriptive **App name** (for example, `Pullbase Config App`). 3. Set the **Homepage URL** to your Pullbase instance (`https://pullbase.example.com`). 4. Set the **Callback URL** to `https://pullbase.example.com/api/v1/github-app/callback` (reserved for future enhancements). 5. Leave the **Webhook** section disabled unless you plan to handle app-level webhooks separately. Grant only the permissions required:

• Repository permissions → Contents: Read-only
• Repository permissions → Metadata: Read-only
• All other permissions: No access

Pullbase only needs read access to fetch configuration files. Additional permissions are unnecessary and increase risk. Install the app on the organization/user that owns your configuration repository. Select the repositories Pullbase should access. After installation, record:

• App ID — Found on the app's settings page under "About"
• App slug — Lowercase name in the app's URL (e.g., pullbase-config from github.com/apps/pullbase-config)
• Installation ID — Found in the URL after installing: github.com/settings/installations/{installation_id}
• Repository ID — Query via GitHub API (see below)
• Private key — Download the .pem file from "Private keys" section

Finding the Repository ID:

# Using GitHub CLI
gh api /repos/{owner}/{repo} --jq '.id'

# Example
gh api /repos/acme/infra-config --jq '.id'
# Output: 964854370

Or via curl:

curl -s https://api.github.com/repos/{owner}/{repo} | jq '.id'

Configure Pullbase

Environment variables

PULLBASE_GIT_ENABLED=true
PULLBASE_GITHUB_APP_ID=2113565
PULLBASE_GITHUB_APP_PRIVATE_KEY_PATH=/config/github-app.pem
PULLBASE_GITHUB_APP_API_BASE_URL=https://api.github.com

Mount the private key into the container at the configured path:

volumes:
  - ./config/github-app.pem:/config/github-app.pem:ro

**Private key security:** - Set restrictive permissions: `chmod 600 github-app.pem` - Never commit the `.pem` file to Git - Use Docker secrets or a secrets manager in production - The `:ro` mount flag ensures the container cannot modify the key

Using Docker secrets (recommended for production):

services:
  central-server:
    image: pullbaseio/pullbase:latest
    environment:
      - PULLBASE_GITHUB_APP_PRIVATE_KEY_PATH=/run/secrets/github_app_key
    secrets:
      - github_app_key

secrets:
  github_app_key:
    file: ./config/github-app.pem

GitHub Enterprise Server

For GitHub Enterprise Server (self-hosted), update the API base URL:

PULLBASE_GITHUB_APP_API_BASE_URL=https://github.mycompany.com/api/v3

The app registration and installation process is the same, but use your GitHub Enterprise URL instead of github.com.

Environment-level configuration

When creating an environment (UI, CLI, or API) you provide GitHub App metadata:

{
  "name": "staging",
  "repo_url": "https://github.com/your-org/configs.git",
  "branch": "main",
  "deploy_path": "environments/staging/config.yaml",
  "installation_id": 89968159,
  "repository_id": 964854370,
  "app_slug": "pullbase-config"
}

CLI validation

Use the bootstrap command to validate credentials locally before storing them on the server:

pullbasectl github-app bootstrap \
  --app-id 2113565 \
  --private-key /config/github-app.pem \
  --installation-id 89968159 \
  --repository-id 964854370 \
  --app-slug pullbase-config

Add --server-url, --admin-token, and environment details to persist the configuration as part of environment creation.

Agent flow

1. The environment stores GitHub App metadata (installation ID, repository ID, app slug).
2. An agent requests GET /api/v1/agent/git-token using its agent token.
3. Pullbase signs a JWT with the app's private key and calls GitHub's /app/installations/{id}/access_tokens endpoint.
4. Pullbase returns the short-lived installation token to the agent, which uses it for git clone.
5. Tokens expire in one hour; agents request fresh ones as needed.

Troubleshooting

- Verify the installation includes the repository. Check [https://github.com/settings/installations](https://github.com/settings/installations) for the app. - Confirm the app has `Contents: Read-only` permission. - Regenerate the `.pem` file from the GitHub App settings and update the mounted secret. - Ensure the file has restricted permissions (readable only by the Pullbase container). - GitHub Apps share a rate limit per installation. Reduce agent poll interval or enable webhooks to decrease token requests. - Check `Retry-After` headers in error responses. - Ensure the webhook secret in GitHub matches `PULLBASE_WEBHOOK_SECRET_KEY`. Use the GitHub CLI to inspect installation details:

gh api /app/installations --jq '.[].id'