GitHub Integration

Connect Codeveira to GitHub using a personal access token. This guide covers creating a fine-grained token, adding your first repository, setting up a push webhook for automatic code reviews, and optionally enabling OAuth sign-in with GitHub.

Prerequisites

A GitHub account with access to the repositories you want to review
A personal access token (created in Step 1)
Admin access to your Codeveira instance

How Codeveira integrates with GitHub

Codeveira connects to GitHub through a read-only API integration and an event-driven webhook. Together they provide automatic, real-time code review creation without any manual steps for developers.

Read-only API access

The personal access token you create in Step 1 lets Codeveira call the GitHub REST API v3. Every call Codeveira makes is read-only — it never writes to your repository, never creates pull requests, and never comments on GitHub directly. Codeveira uses the API to:

Fetch commit metadata: author, committer, message, parents, timestamp
Download the diff for each commit (GET /repos/{owner}/{repo}/commits/{sha} with Accept: application/vnd.github.diff)
Retrieve the repository tree for breadcrumb navigation and file-path resolution
Read raw file content for syntax highlighting in the diff viewer

Fine-grained personal access tokens with Contents: Read on selected repositories are the recommended approach because they limit the blast radius if the token is ever compromised. Classic PATs with the repo scope work too, but they grant broader access across your entire GitHub account.

Automatic review creation via webhooks

The webhook you configure in Step 3 tells GitHub to POST a push event payload to /webhooks/github on every push. Codeveira processes each event as follows:

Validates the HMAC-SHA256 signature in the X-Hub-Signature-256 header against your GITHUB_WEBHOOK_SECRET
Reads the list of commits included in the push
Groups consecutive commits by the same author into a single code review
Creates the review, fetches the diff from the API, and stores it for display
Notifies any assigned reviewers by email
Queues the AI reviewer bot (if configured) to analyze the diff and post inline comments

Webhooks are optional. Without a webhook you can still browse commits and create reviews manually from the Codeveira dashboard. The webhook simply automates this for every push.

API rate limits

GitHub enforces API rate limits: 60 requests/hour for unauthenticated requests and 5,000 requests/hour for authenticated requests. Codeveira uses one authenticated request per commit to fetch the diff, plus a few more for metadata. For active repositories with many commits per hour, always provide a token. If you connect multiple high-volume repositories, consider using separate tokens (each with its own 5,000/hour quota) or a GitHub App token, which has a higher limit.

Create a GitHub access token

Codeveira uses a GitHub personal access token to fetch commits and diffs. Fine-grained tokens are recommended because they limit access to specific repositories and permissions.

Sign in to GitHub and go to Settings → Developer settings → Personal access tokens → Fine-grained tokens
Click Generate new token
Fill in the fields:
- Token name: Codeveira
- Expiration: choose a date that suits your rotation policy
- Repository access: select Only select repositories and choose the repos you want to connect
- Permissions → Contents: set to Read-only
Click Generate token
Copy the token — it is shown only once

Fine-grained PATs are more secure — they scope access to specific repositories and permissions. Classic PATs with the repo scope also work if you prefer, but they grant broader access.

Add the repository in Codeveira

In Codeveira, go to Repositories → New Repository and click the GitHub button at the top of the form. Fill in the following fields:

Name — display name for the repository inside Codeveira
Repo path — the owner and repository name in owner/repo format, e.g. octocat/Hello-World
Access Token — the personal access token you created in Step 1

For public repositories the token is optional, but providing one gives you a much higher API rate limit.

GitHub API rate limit is 60 requests/hr unauthenticated and 5,000 requests/hr with a token. For active repositories, always provide a token.

Click Save. Codeveira will verify the connection by fetching the repository metadata. An error here usually means the repo path is wrong or the token does not have access.

Configure the webhook

A webhook tells GitHub to notify Codeveira on every push so that code reviews are created automatically.

In your GitHub repository, go to Settings → Webhooks → Add webhook

Set the Payload URL to:

https://codeveira.yourdomain.com/webhooks/github

Set Content type to application/json
Set the Secret to the value of GITHUB_WEBHOOK_SECRET from your .env file
Under Which events would you like to trigger this webhook?, choose Just the push event
Make sure Active is checked
Click Add webhook

Without GITHUB_WEBHOOK_SECRET set in your .env, Codeveira will accept unsigned webhook payloads. Always set this secret in production to prevent spoofed push events.

OAuth login (optional)

Enabling OAuth lets your team sign in to Codeveira with their GitHub credentials using the Sign in with GitHub button — no separate password required.

Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
Fill in:
- Application name: Codeveira
- Homepage URL: your Codeveira instance URL, e.g. https://codeveira.yourdomain.com
- Authorization callback URL: https://codeveira.yourdomain.com/users/auth/github/callback
Click Register application
On the next screen, copy the Client ID
Click Generate a new client secret and copy the secret

Add them to your .env:

GITHUB_APP_ID=your_client_id
GITHUB_APP_SECRET=your_client_secret

Restart Codeveira:
```
docker compose restart app
```

The Sign in with GitHub button will appear on the login page after the restart.

Troubleshooting

"404 Not Found"

The repo path is wrong, or the repository is private and the token does not have access to it. Double-check the Repo path field — it must be exactly owner/repo, e.g. octocat/Hello-World. For private repos, verify that the fine-grained token includes that repository under Repository access, or that a classic PAT has the repo scope.

"403 rate limited"

You have hit GitHub's unauthenticated rate limit of 60 requests/hr. Add a personal access token to the repository in Codeveira — each token gets 5,000 requests/hr. If you are already using a token and still hitting limits, consider using separate tokens for different high-volume repositories.

Webhook 400 / 422 error

The most common cause is the wrong content type. Open the webhook in GitHub → Settings → Webhooks, click Edit, and make sure Content type is set to application/json — not application/x-www-form-urlencoded. Also check that the Payload URL is correct and reachable from GitHub's servers.

← GitLab Integration Next: LDAP / Active Directory →