# GitHub Setup

Configure GitHub integration for your self-hosted PullApprove5 deployment.

## Create a GitHub App

Fill in your details below and click "Create GitHub App" to open GitHub with the correct permissions pre-filled.

<div class="bg-zinc-800 border border-zinc-700 p-6 rounded-lg mt-4">
    <div class="space-y-4">
        <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
            <div>
                <label for="github-base-url" class="block text-sm font-medium text-white/90 mb-1">
                    GitHub Base URL
                </label>
                <input
                    type="url"
                    id="github-base-url"
                    value="https://github.com"
                    class="w-full px-2 py-1.5 bg-zinc-900 border border-zinc-600 rounded-md text-white/90 placeholder-gray-400 text-sm focus:outline-none focus:ring-1 focus:ring-gray-400 focus:border-gray-400"
                    placeholder="https://github.com or https://github.example.com"
                >
                <p class="text-xs text-white/60 mt-1">Use your GitHub Enterprise URL if applicable</p>
            </div>
            <div>
                <label for="organization-name" class="block text-sm font-medium text-white/90 mb-1">
                    Organization Name
                </label>
                <input
                    type="text"
                    id="organization-name"
                    value=""
                    required
                    class="w-full px-2 py-1.5 bg-zinc-900 border border-zinc-600 rounded-md text-white/90 placeholder-gray-400 text-sm focus:outline-none focus:ring-1 focus:ring-gray-400 focus:border-gray-400"
                    placeholder="your-organization"
                >
                <p class="text-xs text-white/60 mt-1">The GitHub organization where the app will be created</p>
            </div>
        </div>
        <div>
            <label for="app-domain" class="block text-sm font-medium text-white/90 mb-1">
                App Domain
            </label>
            <input
                type="url"
                id="app-domain"
                value=""
                required
                class="w-full px-2 py-1.5 bg-zinc-900 border border-zinc-600 rounded-md text-white/90 placeholder-gray-400 text-sm focus:outline-none focus:ring-1 focus:ring-gray-400 focus:border-gray-400"
                placeholder="https://pullapprove5.example.com"
            >
            <p class="text-xs text-white/60 mt-1">The domain where your PullApprove5 instance will be hosted</p>
        </div>
        <div>
            <p class="text-sm font-medium text-white/90 mb-2">Permissions</p>
            <div class="text-xs text-white/60 grid grid-cols-2 gap-x-4 gap-y-1">
                <span>Contents: <strong class="text-white/80">Read</strong></span>
                <span>Metadata: <strong class="text-white/80">Read</strong></span>
                <span>Pull requests: <strong class="text-white/80">Write</strong></span>
                <span>Commit statuses: <strong class="text-white/80">Write</strong></span>
                <span>Members: <strong class="text-white/80">Read</strong></span>
                <span>Emails: <strong class="text-white/80">Read</strong></span>
            </div>
            <p class="text-xs text-white/60 mt-2">Events: <strong class="text-white/80">push</strong>, <strong class="text-white/80">pull_request</strong>, <strong class="text-white/80">pull_request_review</strong>, <strong class="text-white/80">membership</strong>, <strong class="text-white/80">team</strong></p>
        </div>
        <div class="flex justify-end">
            <a
                id="github-app-link"
                href="#"
                target="_blank"
                class="px-3 py-2 bg-zinc-700 hover:bg-zinc-600 text-white/90 rounded border border-zinc-600 text-sm disabled:opacity-50 disabled:cursor-not-allowed disabled:hover:bg-zinc-700"
            >
                Create GitHub App
            </a>
        </div>
    </div>
</div>

<script nonce="bN1f9sW04RrpWiQevSVCFA">
document.addEventListener('DOMContentLoaded', function() {
    const githubBaseUrlInput = document.getElementById('github-base-url');
    const organizationNameInput = document.getElementById('organization-name');
    const appDomainInput = document.getElementById('app-domain');
    const githubAppLink = document.getElementById('github-app-link');

    function generateGitHubAppUrl() {
        const githubBaseUrl = githubBaseUrlInput.value.trim().replace(/\/$/, '');
        const organizationName = organizationNameInput.value.trim();
        const appDomain = appDomainInput.value.trim().replace(/\/$/, '');

        const allFieldsValid = githubBaseUrl && organizationName && appDomain;

        if (!allFieldsValid) {
            githubAppLink.href = '#';
            githubAppLink.style.pointerEvents = 'none';
            githubAppLink.style.opacity = '0.5';
            githubAppLink.textContent = 'Create GitHub App';
            return;
        }

        githubAppLink.style.pointerEvents = 'auto';
        githubAppLink.style.opacity = '1';

        const params = new URLSearchParams({
            name: `PullApprove5 ${organizationName}`,
            description: `Self-hosted PullApprove5 for ${organizationName}`,
            url: appDomain,
            'callback_urls[]': `${appDomain}/oauth/github/callback/`,
            request_oauth_on_install: 'true',
            setup_on_update: 'true',
            public: 'false',
            webhook_active: 'true',
            webhook_url: `${appDomain}/webhooks/github/`,
            contents: 'read',
            metadata: 'read',
            pull_requests: 'write',
            statuses: 'write',
            members: 'read',
            emails: 'read'
        });

        params.append('events[]', 'push');
        params.append('events[]', 'pull_request');
        params.append('events[]', 'pull_request_review');
        params.append('events[]', 'membership');
        params.append('events[]', 'team');

        const url = `${githubBaseUrl}/organizations/${organizationName}/settings/apps/new?${params.toString()}`;
        githubAppLink.href = url;
        githubAppLink.textContent = 'Create GitHub App';
    }

    generateGitHubAppUrl();

    githubBaseUrlInput.addEventListener('input', generateGitHubAppUrl);
    organizationNameInput.addEventListener('input', generateGitHubAppUrl);
    appDomainInput.addEventListener('input', generateGitHubAppUrl);
});
</script>

## Configure the GitHub App

After creating your GitHub App, you'll need to generate a few credentials from the app settings page before configuring your deployment.

### Private Key

Click **"Generate a private key"** to download a `.pem` file. This is a multiline file — how you pass it as an environment variable depends on your deployment method. Some systems require you to replace newlines with literal `\n` characters, while others (AWS Secrets Manager, Vault, K8s Secrets) support multiline values natively. PullApprove normalizes line endings on startup, so both formats work.

### Client Secret

Click **"Generate a new client secret"** and save the value.

### Webhook Secret

Generate a random secret, for example:

```bash
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
```

Paste this value into the **Webhook secret** field in your GitHub App settings.

## Environment Variables

Set the following environment variables in your [deployment](/docs/self-hosted/deploy/).

```bash
# Public URL of your GitHub App (found on the app's settings page)
GITHUB_APP_URL=https://github.com/apps/pullapprove5-yourorg
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----\n"
GITHUB_WEBHOOK_SECRET=your-generated-webhook-secret
GITHUB_CLIENT_ID=Iv23_abc123def456
GITHUB_CLIENT_SECRET=your-client-secret

# GitHub Enterprise Server only
# GITHUB_URL=https://github.example.com

# GitHub Enterprise Server only: opt in to real avatars if you've
# disabled private mode. Defaults off — initials are shown otherwise.
# See "GHES avatars" below.
# GITHUB_AVATARS_PUBLIC=true

# Status check name
# (default: "pullapprove5")
GITHUB_STATUS_CONTEXT=pullapprove5

# Comma-separated usernames to ignore webhooks from
# (e.g., your-app[bot])
GITHUB_WEBHOOK_SENDER_BLOCKLIST=your-app-name[bot]
```

## Verify

Test that GitHub can deliver webhooks to your PullApprove5 instance:

1. Go to your GitHub App settings page
2. Click on the **"Advanced"** tab
3. Scroll down to "Recent Deliveries"
4. Click **"Redeliver"** on the ping webhook
5. Verify the delivery shows a successful response (status 200)

![GitHub App Advanced tab showing Recent Deliveries and Redeliver button](/assets/docs/img/self-hosted-github-recent-deliveries.71903c5.png)

If the webhook ping is successful, your self-hosted instance is ready. You can now install the GitHub App on repositories to start using PullApprove5.

## GHES avatars

GitHub Enterprise Server runs in **private mode** by default, which gates every web-tier URL — including `/avatars/u/<id>` — behind a session cookie. PullApprove can't replay that cookie when the browser loads an `<img>` for an avatar, so by default PullApprove renders **deterministic initials badges** for user and organization avatars on GHES.

If you've disabled private mode on your GHES instance (Management Console → "Require authentication for all pages and API endpoints" off), set `GITHUB_AVATARS_PUBLIC=true` in PullApprove's environment to emit real avatar URLs instead of initials.

On `github.com` deployments avatars always work — the public CDN handles everything and the variable is ignored.