Docs
Deploy Convoy

GitHub Integration

Register a GitHub App so projects can connect a repository and browse its pull requests.

Projects connect one GitHub.com repository under Project settings → Integrations. Every project member, viewers included, can then read its open pull requests and their diffs on the project's Pull Requests page. Convoy reads with the App's installation credentials, so reading needs no GitHub account; commenting and other changes use each member's own, linked under Link your GitHub account.

Without the variables below, the GitHub integration page says GitHub isn't set up and the rest of Convoy works as usual. Local-demo deployments always show GitHub as unavailable: they have no signed-in user to bind a connection to.

Register the GitHub App

Create the App under your GitHub organization: Settings → Developer settings → GitHub Apps → New GitHub App.

SettingValue
Callback URLhttps://<your-app-host>/integrations/github/callback (your NEXT_PUBLIC_APP_URL plus that path)
Request user authorization (OAuth) during installationOff
Setup URLThe Callback URL again: https://<your-app-host>/integrations/github/callback
Redirect on updateOn
Webhook URLhttps://<your-convex-site-host>/api/integrations/github/webhook (the Convex HTTP Actions URL, ending in .convex.site on Convex Cloud)
Webhook secretA long random string; it becomes GITHUB_APP_WEBHOOK_SECRET
User-to-server token expiration (Optional features)Opt in. Members' tokens then last 8 hours and Convoy renews them as they're used

Grant these repository permissions from the start. Changing an App's permissions later makes every connected organization's owner approve again, and an organization that never approves stops syncing.

PermissionAccess
Pull requestsRead and write
IssuesRead and write
ContentsRead and write
ChecksRead and write
Commit statusesRead-only
MetadataRead-only

Subscribe to the Pull request, Installation, and Installation repositories events. GitHub also sends every App the GitHub App authorization event, with no subscription; Convoy uses it to ask a member who revoked the App to reconnect. Convoy reads with the App's installation credentials, and every write, such as a comment, acts as the member's own GitHub account.

After creating the App, open its Credentials page. Generate a client secret under Client secrets and a private key under Key pairs; GitHub shows the secret only once and downloads the key as a .pem file. Note the App ID, the client ID, and the App's URL slug (https://github.com/apps/<slug>) from the General page.

Convert the private key

GitHub downloads the key as PKCS#1 (BEGIN RSA PRIVATE KEY). Convoy signs with Web Crypto, which needs PKCS#8 (BEGIN PRIVATE KEY):

openssl pkcs8 -topk8 -nocrypt -in convoy.private-key.pem -out convoy.pkcs8.pem

If you set the unconverted key, Convoy treats GitHub as not set up and logs a warning that names the variable.

Set the variables

Set these on the Convex deployment, never as NEXT_PUBLIC_* variables:

npx convex env set GITHUB_APP_ID 123456
npx convex env set GITHUB_APP_SLUG convoy-acme
npx convex env set GITHUB_APP_CLIENT_ID Iv23li...
npx convex env set GITHUB_APP_CLIENT_SECRET ...
npx convex env set GITHUB_APP_WEBHOOK_SECRET ...
npx convex env set GITHUB_APP_PRIVATE_KEY -- "$(cat convoy.pkcs8.pem)"

NEXT_PUBLIC_APP_URL on the Convex deployment must match the Callback URL's host, since Convoy sends it as the OAuth redirect_uri.

Connect a repository

  1. As a project admin with admin access to the repository on GitHub, open Project settings → Integrations → GitHub and click Connect GitHub.
  2. Authorize on GitHub. You return to the GitHub page with a repository picker.
  3. If the repository isn't listed, click Add repository. GitHub's install page opens in a new tab: install the App, or add the repository to an existing installation. GitHub then returns to Convoy's Setup URL, which closes the tab when the browser allows it. Switch back to Convoy and the list reloads.
  4. Pick the repository and confirm that every project member can read it.

Convoy imports the open pull requests in the background, and webhooks keep them current. Disconnecting hides them right away; Convoy keeps their metadata for 30 days so a reconnect brings them back, then deletes it.

Test setup

Use a separate App per deployment (dev, preview, production), each with its own callback and webhook URLs. For a dev deployment, a test organization with one throwaway repository where you are an admin is enough. GitHub must reach the webhook URL; Convex Cloud's .convex.site URL works without tunneling.

To comment on or change pull requests, each member links their own GitHub account once per Convoy organization: Profile settings → Connected accounts → Connect, the Your GitHub account row on the project's GitHub page, or Connect GitHub to comment... on a pull request. GitHub asks them to authorize the App, then returns them to where they started. Comments, reviews, inline comments, reviewer requests, closing, reopening, drafts, archiving, assignees, merging, and Update branch then run as that account, with whatever access GitHub gives it on the repository: read access to comment and review, triage access to close, reopen, archive, assign, and request reviewers, write access to convert to draft, mark ready for review, merge, update the branch, and delete a merged branch. Disconnect unlinks it and revokes Convoy's token. Leaving the organization unlinks it too.

On this page