GitHub App Setup

Connect zkGrants to your GitHub repositories

📋Overview

The zkGrants GitHub App enables automatic fetching of your repositories and branches when creating grants. It also allows the platform to verify PR merges and CI status for proof generation via webhooks.

Note: You can also manually enter repository information without installing the GitHub App, but you won't get auto-complete suggestions or real-time webhook updates.

For End Users

Prerequisites

A GitHub account (the one you'll use to create grants)
Admin access to the repositories you want to create grants for
Signed in to zkGrants with your GitHub account

Navigate to GitHub App Installation

Go to the zkGrants GitHub App page on GitHub or use the direct installation link:

https://github.com/apps/zkgrants/installations/new

Or click the button below to install directly:

Install GitHub App

Select Account or Organization

Choose whether to install the app for your personal account or an organization where you have admin permissions.

Tip: If you're creating grants for an organization's repositories, you'll need to install the app on that organization.

Configure Repository Access

You can choose to grant access to:

All repositories
Includes future repositories automatically
Only select repositories
Choose specific repos for grants (recommended for security)

Review Permissions

The zkGrants app requests the following permissions:

Permission	Access	Purpose
Contents	Read	List branches, verify commits
Pull Requests	Read	Verify PR merge status
Checks	Read	Verify CI/workflow status
Metadata	Read	Basic repo information
Actions	Read	List workflows for CI-based grants

Note: zkGrants only requires read access. We never write to your repositories.

Complete Installation

Click "Install" to complete the setup. You'll be redirected back to zkGrants.

Done! Your repositories will now appear when creating grants.

For Developers (Self-Hosting)

If you're self-hosting zkGrants or developing locally, you'll need to create your own GitHub App. GitHub Apps are preferred over OAuth Apps as they provide:

Fine-grained repository permissions
Webhook support for real-time updates
Higher API rate limits
Installation on specific repositories

1Create a GitHub App

Go to GitHub Settings → Developer Settings → GitHub Apps → New GitHub App:

Create GitHub App

Basic Information

GitHub App name:zkGrants Dev(must be unique)

Homepage URL:http://localhost:3000

Description:Development instance of zkGrants

Identifying and authorizing users

Callback URL:http://localhost:3000/api/auth/callback/github

Request user authorization (OAuth) during installation

Post installation

Setup URL (optional):http://localhost:3000/api/github/app/install/callback

Redirect on update

Webhook

Active

Webhook URL:https://your-domain.com/api/github/webhooks

Note: For local development, use a tunnel service like ngrok or smee.io to receive webhooks.

Webhook secret:Generate a secure random string (e.g., via openssl rand -hex 32)

Repository Permissions

Permission	Access Level
Actions	Read-only
Checks	Read-only
Contents	Read-only
Metadata	Read-only
Pull requests	Read-only

Subscribe to events

Where can this GitHub App be installed?

Any account

2Generate Private Key

After creating the app, scroll down to the "Private keys" section and click "Generate a private key". Save the downloaded .pem file securely.

⚠️ Security: Keep your private key secure and never commit it to version control. Use environment variables or a secrets manager.

3Generate Client Secret

In the app settings, find the "Client secrets" section and click "Generate a new client secret". Copy it immediately as it won't be shown again.

4Configure Environment Variables

Add the following to your .env.local file:

# NextAuth.js
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=generate-with-openssl-rand-base64-32

# GitHub App Configuration
GITHUB_APP_ID=123456                          # From app settings page
GITHUB_APP_SLUG=your-app-name                 # URL slug (lowercase)
GITHUB_APP_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx     # From app settings
GITHUB_APP_CLIENT_SECRET=xxxxxxxxxxxxxxxx     # Generated client secret

# GitHub App Private Key (replace newlines with \n)
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----"

# Webhook Secret (same as configured in GitHub App settings)
GITHUB_WEBHOOK_SECRET=your-webhook-secret-here

# Public app slug for frontend (optional, for install button)
NEXT_PUBLIC_GITHUB_APP_SLUG=your-app-name

Tip: To convert the private key for the environment variable, you can use:

awk 'NF {printf "%s\\n", $0}' your-app.private-key.pem

5Run Database Migrations

Make sure to run the database migrations to create the necessary tables:

pnpm db:migrate

Production Configuration

For production, update the URLs in your GitHub App settings:

Homepage URL:https://zkgrants.io

Callback URL:https://zkgrants.io/api/auth/callback/github

Setup URL:https://zkgrants.io/api/github/app/install/callback

Webhook URL:https://zkgrants.io/api/github/webhooks

Troubleshooting

Repository not appearing?

Check the following:

The GitHub App is installed on the correct account/org
The repository is included in the app's access list
Try refreshing the page or signing out and back in

Webhooks not being received?

Verify the following:

Webhook URL is accessible from the internet
GITHUB_WEBHOOK_SECRET matches the secret in GitHub App settings
Check GitHub App settings → Advanced → Recent Deliveries for errors
For local dev, ensure your tunnel (ngrok/smee) is running

Need to add more repositories?

Go to your GitHub Settings → Applications → zkGrants → Configure, and add additional repositories.

Want to revoke access?

Go to your GitHub Settings → Applications → zkGrants and click "Uninstall". This won't affect existing grants.

Next Steps

Now that you've set up the GitHub integration, you're ready to create your first grant!

Create a Grant Back to Docs