Skip to main content
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

Register the app

  1. Visit 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.
2

Configure permissions

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

Install the app

Install the app on the organization/user that owns your configuration repository. Select the repositories Pullbase should access.
4

Capture credentials

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

  • 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'