Connecting Your Repositories
GitVelocity integrates with your version control provider (GitHub, Bitbucket, or GitLab) during the signup flow. You choose your platform, authorize read-only access, and select which repositories to track. From that point on, every merged pull request is automatically analyzed and scored. Code is processed in real-time and is never stored after scoring completes.
GitHub
GitVelocity connects to GitHub through a dedicated GitHub App installed on your company's GitHub organization. To measure only your own work, without a GitHub admin, see Measuring just your own work.
Permissions Required
The GitVelocity GitHub App requests the minimum permissions necessary to analyze merged pull requests:
| Permission | Access Level | Why It Is Needed |
|---|---|---|
| Pull requests | Read | Read PR diffs, titles, descriptions, and merge status |
| Commits | Read | Access commit messages and metadata associated with PRs |
| Repository metadata | Read | Identify repository names, languages, and structure |
GitVelocity does not request write access to your repositories. It cannot modify code, merge pull requests, or change any repository settings.
Setup
During the GitVelocity signup flow:
- Under What do you want to measure?, choose My team's repos, then select GitHub as your provider.
- You are redirected to GitHub to install the GitVelocity GitHub App.
- Select your company's GitHub organization. If you pick your personal account instead, GitVelocity offers to score your own work with that install in a personal workspace, or to go back and connect your company's repos.
- Choose which repositories to grant access to -- either all repositories or a specific subset.
- Click Install to complete the authorization.
- You are returned to GitVelocity to confirm your organization details.
If you already installed the GitVelocity GitHub App on your organization but never finished signing up, you don't need to uninstall it. Under Connect GitHub, choose Already installed GitVelocity on your GitHub org? Connect it. You sign in with GitHub, pick your organization from the list of organizations that already have the app, and continue from there. The same option appears under Settings > Repositories when a workspace has no GitHub connection.
If your team already uses GitVelocity, you may not need to install anything. When you pick a personal account, or an organization that is already connected, GitVelocity checks whether your work email matches an existing workspace. If it does, it offers to let you join that workspace. The same offer appears on Bitbucket and GitLab when the workspace or group is already connected. If your email address is not verified yet, verify it first, then sign out and back in.
Once the install completes, the Repositories settings page confirms the connection and shows the install scope. A link at the bottom takes you to the Processing Log page to inspect webhook deliveries.
When you are not a GitHub organization owner
Only an owner of a GitHub organization can install a GitHub App on it. If you aren't one, you have two ways in.
Request the install on GitHub. At step 5, GitHub shows a Request button instead of Install. Click it. GitHub notifies your organization's owners and sends you back to GitVelocity, which shows Request sent to your GitHub org owners. If that screen asks you to Confirm your GitHub account, do it: that is how GitVelocity knows which request is yours. When an owner approves the request on GitHub, GitVelocity creates your company's workspace, makes you its owner, and emails you. From there, add an API key to start scoring, and invite your teammates (including the owner who approved you) from Settings > Team.
If an owner approves before you've confirmed your GitHub account, GitVelocity keeps the approval for 30 days. Confirm your account in that time and GitVelocity acts on the approval right away, the same way it would have when the owner approved: it creates your company's workspace, or adds you to the one set up from that approval, or, if your organization already had a workspace, emails you which one it is and who to ask for access. You don't have to ask again.
While your request is waiting, onboarding shows how long it has been pending. Requests expire after 30 days, and you can cancel yours from the same banner with Cancel request. To score your own pull requests in the meantime, choose While you wait, start with your own work.
If GitVelocity already has a workspace for that organization, approving the request doesn't create a second one. You get an email naming the existing workspace and who to ask for access.
Ask your admin by email. Choose Ask your admin, either on the request screen, under Not a GitHub organization admin? on the install step, or on the personal-account screen. Enter up to three people who can install GitHub apps at your company, edit the note if you like, and use Preview email to see exactly what they'll get. The email says who asked, that GitVelocity reads merged pull request diffs read-only and doesn't store code, and that your company supplies its own API key. It includes an install link. When someone installs from that link, they see your name first. They become the workspace owner, and you're added to it automatically.
Your account's email address must be verified before you can send. Each address can be asked once a day, and you can send up to five requests a day. If a teammate already asked the same person today, GitVelocity adds your name to that request instead of sending a second email. To share the link in Slack or anywhere else, use Copy install link.
Measuring just your own work
If you have no company organization to connect, or nobody who can install the app, you can still score your own work in a personal workspace. Choose Just my own work under What do you want to measure?, or, if you already belong to a workspace, choose Create personal workspace from the workspace menu. A personal workspace can import your merged pull requests on public repos without installing anything, score the repos on your personal GitHub account through the GitHub App, and take scores from gv score. See Personal Workspaces for setup, what you see, and how it relates to your company workspace.
Repository Selection
During installation, GitHub gives you two options:
All repositories -- GitVelocity automatically tracks every repository in the organization, including any created in the future.
Select repositories -- Choose specific repositories to track. You can add or remove repositories later from GitHub > Settings > Applications > GitVelocity without reinstalling.
Starting with a subset of active repositories and expanding coverage over time works well for most teams.
After Installation
Once the GitHub App is installed, scoring is fully automatic:
- GitVelocity listens for pull request merge events on your selected repositories.
- When a PR merges, the diff is read and queued for analysis.
- The AI model evaluates the PR across six dimensions and produces a 0--100 score.
- The score appears on your dashboard, typically within a few minutes of the merge.
No additional configuration is needed.
Bitbucket
GitVelocity supports Bitbucket Cloud workspaces through an OAuth integration.
Permissions Required
The Bitbucket OAuth consumer requests read access to:
- Pull requests -- read diffs, titles, descriptions, and merge status
- Repositories -- identify repository names and metadata
- Account -- identify workspace membership
As with GitHub, GitVelocity does not request write access. It cannot modify code or change any workspace settings.
Setup
During the GitVelocity signup flow:
- Select Bitbucket as your provider.
- You are redirected to Bitbucket to authorize the GitVelocity OAuth consumer.
- Grant read access to your Bitbucket workspace.
- You are returned to GitVelocity to select which repositories to track.
After Connection
Once connected, Bitbucket works identically to GitHub. Merged pull requests are automatically analyzed and scored. Manage which repositories are tracked from the Settings page within GitVelocity.
GitLab
GitVelocity supports GitLab groups and projects through an OAuth integration, following the same model as Bitbucket.
Permissions Required
The GitLab OAuth application requests read access to:
- Merge requests -- read diffs, titles, descriptions, and merge status
- Repositories -- identify project names and metadata
- Profile -- identify group membership
As with GitHub and Bitbucket, GitVelocity does not request write access. It cannot modify code or change any project settings.
Setup
During the GitVelocity signup flow:
- Select GitLab as your provider.
- You are redirected to GitLab to authorize the GitVelocity OAuth application.
- Grant read access to your GitLab group.
- You are returned to GitVelocity to select which projects to track.
After Connection
Once connected, GitLab works identically to GitHub and Bitbucket. Merged merge requests are automatically analyzed and scored. Manage which projects are tracked from the Settings page within GitVelocity.
Troubleshooting
Organization or Workspace Approval Required
Some organizations require an admin to approve new app installations or OAuth integrations. On GitHub, see When you are not a GitHub organization owner: GitVelocity keeps your request and sets up your workspace when an owner approves it. On Bitbucket or GitLab, if you see a pending approval message after attempting to connect, ask a workspace admin or group owner to approve the GitVelocity integration from their admin settings.
Private Repositories
GitVelocity works with both public and private repositories. The integration permissions grant read access to PR diffs regardless of repository visibility. If a private repository does not appear in the selection list, confirm that the integration has been granted access to it.
Missing Scores
If scores are not appearing after a pull request merges:
- Verify the repository is included in your GitVelocity integration settings.
- Confirm the PR was actually merged (not closed without merging).
- Allow a few minutes for analysis to complete. Each PR is typically scored within 30 seconds, but there may be a queue during periods of high activity.
Reinstalling or Reconfiguring
To change which repositories GitVelocity can access:
- GitHub: Go to GitHub > Settings > Applications > GitVelocity and modify the repository selection.
- Bitbucket: Manage connected repositories from the Settings page within GitVelocity.
- GitLab: Manage connected projects from the Settings page within GitVelocity.
You do not need to uninstall and reinstall to change repository access.