Skip to main content
AI Review integrates with GitHub by receiving webhook events and posting review comments back on pull requests. This page walks you through setting up the connection for both GitHub.com and GitHub Enterprise.

​
Prerequisites

Before you begin, gather the following:
  • GitHub base URL — See the tabs below.
  • Access token — A GitHub personal access token or fine-grained token.
  • Webhook secret — A secret string you choose; GitHub will include an HMAC-SHA256 signature in every delivery so AI Review can verify authenticity.
Set the base URL to:
https://api.github.com
The access token must have the repo scope (or the equivalent fine-grained permissions: read access to repository contents and metadata, write access to pull request comments).
The access token must have sufficient permissions to read repositories and post comments on pull requests. Without the correct scopes, project sync and comment posting will fail.

​
Setup

1

Add a platform configuration

In the AI Review dashboard, go to Platform Configs and click Add.Fill in the fields:
FieldValue
NameA label for this connection (e.g. GitHub.com)
Platform typeGitHub
Base URLhttps://api.github.com or your enterprise URL
Access tokenYour GitHub access token
Webhook secretThe secret string you chose
Save the configuration.
2

Sync projects

Go to Project Management and click Sync.Select the platform configuration you just created and start the sync. AI Review fetches all accessible repositories from GitHub and imports them into the project list.
If the sync fails, verify the base URL is correct, the token has the right scopes, and the GitHub instance is reachable from the AI Review server.
3

Enable auto-review on a project

In Project Management, locate the repository you want to enable and open its settings.Turn on Auto Review. You can also configure:
  • The AI configuration to use for this project.
  • Review templates.
  • Default reviewers and assignees.
4

Configure the GitHub webhook

In your GitHub repository, go to Settings → Webhooks and click Add webhook.
Payload URL:    https://<your-ai-review-host>/api/webhook/github
Content type:   application/json
Secret:         <the webhook secret you set in the platform config>
Under Which events would you like to trigger this webhook?, select at minimum:
  • Pull requests
  • Issue comments (required for the /ai-review manual trigger command)
Click Add webhook.GitHub signs every delivery using HMAC-SHA256 and sends the signature in the X-Hub-Signature-256 header. AI Review verifies this signature against all stored GitHub platform configurations before processing any event.

​
Supported events

AI Review processes the following GitHub webhook events:
x-github-event headeractionBehavior
pull_requestopenedTriggers auto-review
pull_requestsynchronizeTriggers auto-review
pull_requestreopenedTriggers auto-review
issue_commentcreated (on a PR)Triggers manual review when the comment body starts with /ai-review
All other event types and actions are acknowledged with HTTP 200 but are not processed.

​
Manual trigger command

Posting a comment on a pull request with the text /ai-review (optionally followed by arguments) triggers a manual review. The comment must be on a PR, not a plain issue.

​
Review gate

Receiving a webhook event does not unconditionally start a review. Before queuing a review job, AI Review checks:
  1. The X-Hub-Signature-256 signature is valid for at least one stored GitHub platform configuration.
  2. The repository exists in the system (was synced).
  3. The project has review enabled.
  4. Auto-review is turned on for the project (for automatic triggers).
  5. An AI configuration is available for the project.
If any check fails, the webhook returns HTTP 200 with a descriptive message and no review is queued.

​
Troubleshooting

AI Review validates the HMAC-SHA256 signature in the X-Hub-Signature-256 header against every stored GitHub platform configuration. If none match, the request is rejected with HTTP 401.
  • Confirm the webhook secret in GitHub exactly matches the webhook secret stored in the AI Review platform configuration.
  • If you have multiple GitHub platform configurations, ensure at least one has the correct secret for this webhook.
  • Re-enter the secret on both sides if you are unsure which value was saved.
Check the following in order:
  1. Project not synced — The repository must appear in Project Management. Run a sync if you recently added the repository to GitHub.
  2. Project or auto-review disabled — Open the project settings in AI Review and confirm that the project is enabled and Auto Review is turned on.
  3. AI configuration missing — The project must have an AI configuration assigned. Go to the project settings and select or create an AI config.
  4. Unsupported event type — Only pull_request events with actions opened, synchronize, and reopened, and issue_comment events on PRs are processed. Check the Recent Deliveries tab in the GitHub webhook settings to see which event type was sent.
  • Confirm the base URL is correct for your setup (use https://api.github.com for GitHub.com).
  • Verify the access token has not expired and has the repo scope.
  • Check that the token grants access to the repositories you expect to import.
  • Confirm the GitHub instance is reachable from the AI Review server.
  • Verify the access token has permission to post comments on pull requests.
  • Check the AI Review server logs for errors from the GitHub API response.
  • Confirm the project’s AI configuration points to a working AI provider.

Build docs developers (and LLMs) love

Get started for freeTalk to us