GitHub App Setup

Prerequisites

• A GitHub account (personal or organization)
• Admin access to your Grid instance
• Your Grid instance must be publicly accessible (GitHub needs to send webhooks to it)

Step 1: Create the GitHub App

1. Go to GitHub → Settings → Developer settings → GitHub Apps → New GitHub App.
   Direct link: https://github.com/settings/apps/new
2. Fill in the basic information:
   • GitHub App name: Something like Grid Deploy or MyOrg Grid (must be globally unique)
   • Homepage URL: Your Grid instance URL, e.g. https://grid.example.com
   • Callback URL: https://grid.example.com/auth/github/app/callback (only needed if you enable "Request user authorization during installation")
   • Request user authorization (OAuth) during installation: Leave unchecked for most setups

Step 2: Configure the Webhook

On the same creation page, under Webhook:

• Active: Checked
• Webhook URL: https://grid.example.com/api/v1/webhooks/github/
• Webhook secret: Generate a random string and save it. You'll need to set this as GITHUB_WEBHOOK_SECRET in your Grid environment.

Step 3: Set Permissions

Under Permissions → Repository permissions, set:

Under Permissions → Account permissions, no changes needed.

Step 4: Subscribe to Events

Under Subscribe to events, check these:

• Installation — Track when the app is installed or uninstalled
• Installation repositories — Track repos added/removed from the installation
• Pull request — Trigger preview environments on PRs
• Push — Trigger deployments on push

Step 5: Create the App

Click Create GitHub App. After creation:

1. Generate a private key: Scroll down to the "Private keys" section and click Generate a private key. A .pem file will be downloaded.

2. Note your App ID: It's shown at the top of the app settings page.

3. Note the App slug: Visible in the URL — https://github.com/apps/YOUR-SLUG.

Step 6: Configure Grid

Add these to your Grid .env file (or set as environment variables):

# GitHub App Configuration
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"

# Webhook secret (same one you set in GitHub)
GITHUB_WEBHOOK_SECRET=your-random-secret-here

Restart your Grid backend after updating the environment variables.

Step 7: Install the App on Your Repos

1. In Grid, go to Settings → GitHub → GitHub App and click Install App.
2. GitHub will show you the installation page — select which repos to grant access to.
3. After installation, you'll be redirected back to Grid. The installation is now linked to your account.

Alternatively, install directly on GitHub:

• Go to https://github.com/apps/YOUR-SLUG/installations/new
• Select repos and confirm

Step 8: Verify

• Push a commit to a connected repo — a deployment should trigger automatically
• Open a PR — a preview environment should be created
• Check the commit on GitHub — a deployment status badge should appear

Why These Permissions?

Troubleshooting

Webhook deliveries failing (401/403)

Verify that GITHUB_WEBHOOK_SECRET in your Grid .env matches the webhook secret configured in the GitHub App settings.

App not showing up after install

Make sure the callback URL in the GitHub App settings matches your Grid instance URL exactly: https://your-grid-domain.com/auth/github/app/callback

Private repos not building

Ensure the app has Contents: Read-only permission and that you've selected the specific repos (or "All repositories") during installation.

Commit statuses not appearing

Check that Commit statuses: Read & write permission is set. Also verify the app installation covers the repository in question.

Organization Installations

If you install the app on a GitHub organization:

• All members can deploy from org repos (once linked in Grid)
• Webhook events are scoped to the org
• The org admin may need to approve the installation depending on org settings

OAuth vs GitHub App

Grid supports both OAuth and GitHub App integrations. They can coexist: