Skip to content

Mergebot Quickstart – Self-Hosted with GitHub App

Follow these steps to run Mergebot ondemand against your repositories using your own GitHub App.

1. Create a GitHub App

  1. Go to Settings → Developer settings → GitHub Apps → New GitHub App.
  2. Fill in:
  3. App name: e.g. Mergebot Self-Hosted
  4. Webhook URL: http://YOUR-HOST/webhook (not used in ondemand but required)
  5. Callback URL: leave blank or placeholder (https://example.com/unused)
  6. Permissions (Repository level)
  7. Contents: Read & write
  8. Pull requests: Read & write
  9. Issues: Read & write
  10. Checks: Read & write (optional)
  11. Save, then Generate a private key → download private-key.pem.
  12. Install the App on the repository/org you want Mergebot to manage.
  13. Note the App ID (Settings page).
  14. Installation ID is optional – Mergebot will auto-discover it.

2. Prepare environment variables

export GITHUB_APP_ID=123456               # your App ID
export GITHUB_APP_PRIVATE_KEY="$(cat private-key.pem)"
# Optional – only if auto-discovery fails
# export GITHUB_APP_INSTALLATION_ID=987654

PEM formatting and CI secrets

  • Provide the raw PEM (not a file path). The value should include the header/footer lines.
  • Secrets work as:
  • Multiline PEM (recommended): paste the full contents including line breaks.
  • Single-line PEM with 'n': you can store the PEM on one line with literal 'n' newlines. Mergebot accepts both formats.
  • GitHub Actions: set GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY as repository or org secrets; the workflow examples pass them through to Docker.

You may instead set these keys in mergebot/config.yaml or .mergebot.yml:

repository:
  type: github
  github:
    app_id: 123456
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      YOUR-PEM-CONTENT-HERE
      -----END RSA PRIVATE KEY-----
    # installation_id: 987654   # optional

3. Run Mergebot ondemand

Ensure your mergebot/config.yaml (or the file pointed to by CONFIG_PATH) lists the repositories under repository.projects. Then run:

CONFIG_PATH=mergebot/config.yaml mergebot ondemand

Mergebot will:

  1. Generate a JWT and exchange it for an installation access token.
  2. Analyse open pull requests for each configured project.
  3. Comment / approve according to your .mergebot.yml.

Troubleshooting

Symptom Resolution
GitHub App credentials missing… Ensure GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY are set or in config.
Could not determine installation_id Pass GITHUB_APP_INSTALLATION_ID env var (see Installations page URL).
401/403 errors Check that the App is installed on the target repo and has correct permissions.
Private key path error Provide full path or inline PEM via env.

You are now ready to automate PR reviews with your self-hosted Mergebot!