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/newOr click the button below to install directly:
Install GitHub AppSelect 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.
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_SECRETmatches 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!