Git Integration

Connected during onboardingThe Checksum team connects your code and tests repositories with you during onboarding. Come back here to check the connection status, review permissions, switch repositories, connect an additional repository, or reconnect after a token rotation. Your Checksum contact can also make these changes for you.

At a glance

Provider	How Checksum connects	Can host your tests repo?
GitHub	The Checksum GitHub App	Yes
GitHub Enterprise Cloud (`*.ghe.com`)	A GitHub App on your instance	Yes
GitLab	An access token	Yes
Bitbucket	An access token	Yes
Azure DevOps	A personal access token	Code repository only

Reference for AI: Git providers at a glance

Provider	Connection method	Code repository (read-only)	Tests repository (read/write)
GitHub	Checksum GitHub App	Supported	Supported
GitHub Enterprise Cloud	GitHub App on your `*.ghe.com` instance	Supported	Supported
GitLab	Personal or project access token	Supported	Supported
Bitbucket	Access token	Supported	Supported
Azure DevOps	Personal access token (PAT)	Supported	Not supported

Where: web app → Settings → Git Integration. Checksum connects repositories during onboarding.
Webhooks (push, PR, installation events) are set up automatically and keep the repo mirror in sync.
Not supported: GitHub Enterprise Server (self-hosted), and tests repositories on Azure DevOps.
Removing the integration disables test generation and auto-healing.

Developer guide

The access Checksum needs on each provider

Required permissions

Checksum needs read-only access to your application code, and read and write access to your tests repository, where it opens pull requests. On GitHub you simply approve the Checksum app, which requests these permissions for you. On GitLab, Bitbucket, and Azure DevOps you create a token with the scopes below.

Provider	Code repository (read-only)	Tests repository (read/write)
GitHub (GitHub App)	`Metadata: Read`, `Contents: Read`, `Pull requests: Read`	`Metadata: Read`, `Contents: Read + Write`, `Pull requests: Read + Write`, `Issues: Read + Write`, `Actions: Read + Write`
GitLab (personal or project access token)	Scopes `read_api`, `read_repository`; role `Reporter`	Scopes `api`, `write_repository`; role `Developer`
Bitbucket (access token)	`Repositories: Read`, `Pull requests: Read`	`Repositories: Read + Write`, `Pull requests: Read + Write`
Azure DevOps (PAT)	`Code (Read)`	Not supported today

A few provider details to know. On GitHub, if one app installation covers both repositories, GitHub shows the combined request (read + write on actions, code, issues, and pull requests), but write access is only used on the tests repository. On GitLab, protected branches may need Maintainer, or a branch rule that lets Checksum merge. On Bitbucket, repository access and pull-request access are separate permissions, so grant both. Azure DevOps is supported for code repositories only; Checksum-managed tests repositories aren’t supported there.

Reference for AI: provider permissions

Provider	Credential	Code repository (read-only)	Tests repository (read/write)
GitHub	GitHub App (no scopes to choose)	`Metadata: Read`, `Contents: Read`, `Pull requests: Read`	`Metadata: Read`, `Contents: Read + Write`, `Pull requests: Read + Write`, `Issues: Read + Write`, `Actions: Read + Write`
GitLab	Personal or project access token	Scopes `read_api`, `read_repository`; role `Reporter`	Scopes `api`, `write_repository`; role `Developer` (`Maintainer` or a branch rule for protected branches)
Bitbucket	Access token	`Repositories: Read`, `Pull requests: Read`	`Repositories: Read + Write`, `Pull requests: Read + Write`
Azure DevOps	PAT	`Code (Read)`	Not supported

Write access is used only on the tests repository. Checksum never writes to the code repository.
GitHub combined installations show read + write on actions, code, issues, and pull requests.
Bitbucket: grant repository and pull-request access separately.

▦

In the Checksum web app

Connect providers, change repositories, and check status in Settings → Git Integration

Add or reconnect a repository

Use these steps to connect an additional repository, move to a different Git provider, or reconnect after an app was uninstalled or a token expired. The same steps are used during onboarding.

GitHub
GitHub Enterprise (ghe.com)
GitLab
Bitbucket
Azure DevOps

GitHub: install or update the Checksum GitHub App

Open Settings → Git Integration

In the Checksum web app. Under Codebase repository (or Tests Repository), click Connect / Install GitHub App.

Authorize on GitHub

You’re redirected to GitHub to authorize the Checksum app. This may require an organization owner.

Choose repositories

Grant access to only the repositories Checksum needs, then complete the installation.

Select repositories in Checksum

Back in Checksum, pick the tests and code repositories (see Change repositories).

GitHub App authorization — Authorizing the Checksum GitHub App.

If you’re not an organization owner

GitHub can’t complete the install for you directly. The button reads Install and request (or Request), and GitHub emails your organization owners to approve it. Until they do, Checksum shows the app as not installed. To approve the request, an organization owner:

Opens the email notification, or goes to the organization’s Settings → Third-party Access → GitHub Apps.
Finds the pending Checksum request.
Reviews the requested repositories and permissions, adjusting the repository selection if needed.
Clicks Approve (or Install).

Organizations can restrict who installs apps. If repository admins are blocked from installing GitHub Apps, an organization owner must approve or install the Checksum app. Once approved, it shows as active in Settings → Git Integration.Installing the app also sets up the webhooks that keep the repo mirror in sync, and it enables /checksum generate comments on PRs (see Generate Tests).

GitHub Enterprise Cloud with data residency

If your organization lives on a dedicated *.ghe.com subdomain (e.g. acme.ghe.com), connect it from Settings → Git Integration. Connecting takes about two minutes. It installs a Checksum GitHub App on your own instance, so there are no tokens or secrets to share.

Cloud onlyThis is for GitHub Enterprise Cloud with data residency (*.ghe.com). If you’re on standard github.com, use the GitHub steps instead. GitHub Enterprise Server (self-hosted, e.g. github.your-company.com) isn’t supported yet.

What you’ll need

Requirement	Details
A GitHub organization owner	Creating and installing a GitHub App on your organization requires the owner role. If you aren’t an owner, ask one to run this flow.
Your instance host	Your enterprise’s `*.ghe.com` subdomain, e.g. `acme.ghe.com`
Your organization name	The organization inside your enterprise that owns the repositories
Access to Checksum	Signed in at app.checksum.ai with your project open

TipIn the same browser, sign in to GitHub as a member of your *.ghe.com enterprise (not github.com) before you start. The flow opens a page on your enterprise instance.

Open Git Integration

Go to Settings → Git Integration and find Tests Repository or Code Repository. Each has its own connection, so repeat this flow for both if you need both.

Git Integration settings with the GitHub Enterprise connect option

Click "Connect GitHub Enterprise (ghe.com)"

Under Using a private GitHub Enterprise instance?, click Connect GitHub Enterprise (ghe.com). The Connect GitHub Enterprise dialog opens.

Enter your host and organization

Fill in both fields and click Continue.

Field	Example	Notes
GitHub Enterprise host	`acme.ghe.com`	Your `*.ghe.com` subdomain. No `https://`, just the host.
GitHub organization	`acme-engineering`	The organization within your enterprise that owns the repositories

Create the app on your instance

Click Open GitHub. A page on your enterprise instance opens to register the Checksum AI Code (or Checksum AI Tests) app. Checksum has already set the permissions and webhook. Confirm the app name and click Create GitHub App. GitHub then shows the new app with an Install button.

NoteThis step only registers the app. It doesn’t grant access to any repositories yet.

TipUse Open GitHub so the app is created with Checksum’s settings. If it opens on the wrong GitHub account, right-click the button to copy the link, then open it in a tab where you’re signed in as an organization owner.

The Checksum app registered on your enterprise instance

Install the app and choose repositories

Click Install and choose All repositories or Only select repositories (you can add more later). Click Install. GitHub redirects you back to Checksum, and the enterprise integration shows as connected.

Installing the Checksum app and selecting repositories

If the GitHub tab closed before you finished, reopen the dialog and use Reopen GitHub tab to return to the same page. Once connected, select your tests and code repositories exactly as you would for github.com. From there, Checksum can generate and heal tests and open pull requests against your enterprise repositories.

Connect GitLab with an access token

Create a token

Create a personal or project access token. For a code repo: scopes read_api, read_repository, role Reporter. For a tests repo: scopes api, write_repository, role Developer. See GitLab: project access tokens.

Open Settings → Git Integration

Select GitLab.

Enter the token

Paste your GitLab access token. For code repositories, have the Project ID ready.

Select the projects

Choose the projects to connect as tests and/or code repository.

The token’s user (or the project or group token itself) needs at least the role above on the matching project. A Guest can’t clone a private project, and a Reporter can’t push branches or open merge requests.

Test the token before adding itRun git clone https://oauth2:<TOKEN>@gitlab.com/your-group/your-repo.git. If it clones, Checksum can read the repository with that token.

Connect Bitbucket

Gather details

Your Workspace name and Repository name.

Create an access token

Code repo: Repositories: Read, Pull requests: Read. Tests repo: Repositories: Read + Write, Pull requests: Read + Write. See Atlassian: repository access tokens.

Connect in Checksum

Enter the workspace, repository, and token under Settings → Git Integration, or send them to your Checksum contact.

Connect Azure DevOps (code repository)

Gather details

Organization, Project, and Repository names.

Create a PAT

Minimum scope: Code: Read. See Microsoft: personal access tokens.

Connect in Checksum

Enter the details under Settings → Git Integration, or send them to your Checksum contact.

Code repositories onlyThe tests repository must be on GitHub, GitLab, or Bitbucket.

Change repositories

Your repositories are selected during onboarding. To point Checksum at a different repository:

Open Settings → Git Integration

Tests Repository

Select the repository that holds your Playwright tests. Checksum opens PRs here. Change it only if your tests move to a different repository.

Code Repository (required)

Select your application source repository. You can change it at any time.

Git Integration repository selection — Selecting the tests and code repositories.

Integration status

The Settings page shows the state of your integration:

Status	Meaning
Active	Connected and working
Not Installed	No GitHub App or GitLab token configured
No Repositories	The app is installed, but no repositories were granted access
No Selected Repository	Repositories are available, but none has been selected yet

Change or remove an integration

Change repositories: go to Settings → Git Integration and update your selection.
Remove the integration: go to Settings → Git Integration and click Remove Integration.

Removing disables deliveryRemoving the Git integration disables test generation and auto-healing, because Checksum can no longer open PRs in your repository.

How it works

What Checksum does with each repository

Tests repository and code repository

Checksum works with two repositories, and they can be the same one:

Repository	What Checksum does	Access
Tests repository (required)	Opens pull requests with generated and healed tests, creates branches, comments, and may auto-merge	Read and write
Code repository (required)	Reads application code and PR context so agents understand your routes, components, and interactions. Checksum never writes to it.	Read-only

Why the code repository mattersThe code repository gives Checksum significantly faster and more accurate detection, and better generation and healing. If your tests live alongside your app code, the same repository is used for both.

Troubleshooting

GitHub won't let me create or install the app (ghe.com)

You’re either not an organization owner or signed in to the wrong GitHub account. Sign in as an owner of your *.ghe.com enterprise and reopen the GitHub tab. On shared machines, a fresh browser profile or incognito window usually fixes it.

The host field won't accept my value (ghe.com)

The host must end in .ghe.com, such as acme.ghe.com. You can paste a full URL, and the field strips https://, any path, and the port. A GitHub Enterprise Server hostname like github.your-company.com won’t work.

I finished on GitHub but Checksum still shows "not connected"

Make sure you clicked Install (not just Create GitHub App) and selected at least one repository, then refresh Settings → Git Integration. The flow is safe to repeat.

Status says "No Repositories"

The app is installed but wasn’t granted any repos. In GitHub, open the app’s installation settings and add the repositories, then refresh.

We use GitHub Enterprise Server (self-hosted)

Not supported yet. Only GitHub Enterprise Cloud with data residency (*.ghe.com) is. Contact Checksum support to discuss options.

GitHub shows the app as not installed after I requested it

An organization owner still has to approve the installation request. See If you’re not an organization owner.

403 "You are not allowed to download code from this project"

The token’s user or role can’t read the repository, for example a GitLab Guest. Recreate the token with at least the minimum role in Required permissions: Reporter for a code repository, Developer for a tests repository.

GitLab says the token is missing a scope

Recreate the token with the scopes listed for that repository in Required permissions: read_api and read_repository for a code repository, api and write_repository for a tests repository.

Checksum can't open pull requests

The token has read access but not write access on the tests repository. Grant write access: GitLab api and write_repository, or Bitbucket Repositories: Read + Write and Pull requests: Read + Write. On GitHub, make sure the app installation includes the tests repository.

Checksum can't merge into a protected GitLab branch

Use a token with the Maintainer role, or add a branch rule that lets Checksum merge.

Test Repository & Config

How the repo mirror reads and writes.

/checksum generate

Trigger generation from a PR comment.

Security & Access

A permissions summary for security review.

Start Here

Managing Your Project

Test Generation

Test Execution

Maintenance & Monitoring

Integrations

Security & Admin

At a glance

Required permissions

Add or reconnect a repository