Access control

Learn how to manage access to your Chromatic account and projects.


Login via OAuth from GitHub, GitLab, or Bitbucket. Chromatic supports the public cloud versions of these services via our self-serve plans.

If you use the on-premise or enterprise versions of GitHub, GitLab, or Bitbucket, we can support you via our enterprise plan. The enterprise plan also offers single sign-on (SSO) and service-level agreements (SLA). We recommend trialing Chromatic first by following these instructions.

If you use other services like Azure DevOps, AWS, etc, you won’t be able to sign in via OAuth. But you can still use Chromatic as a CI-only job using the instructions here.

OAuth Scopes

Depending on your Git provider, Chromatic will request a set of OAuth scopes when you first login. Chromatic uses these permissions to enumerate your list of repos, set PR statuses and retrieve users for assignment to review. Chromatic will never read/write source code.

Git provider Scopes
GitHub ['user:email', 'read:user', 'read:org', 'repo:status']
GitLab ['api']
Bitbucket ['account', 'repository', 'pullrequest', 'webhook']

GitHub App permissions

Chromatic’s GitHub App enables UI Review for pull requests. We need additional permissions to access pull request information and add PR checks.

  • ✅ Read access to metadata
  • ✅ Read and write access to checks and pull requests
  • ✅ Read access to organization members (for collaborators)
  • 🔒 We do not request access to your code


Chromatic mirrors access permissions at the “team” level to make permissions management quick and easy. Share access with your GitHub organization, Bitbucket group, or GitLab team by adding that account to Chromatic via the menu.

Account menu



Permissions carry over at the repository level for collaborators. For example, if a person does not have access to repository in your Git provider they will also not have access to it in Chromatic. To verify UI tests and review pull requests collaborators must have write access to the repo.

Permission level What collaborators can do
Organization: member View / change account settings, view / add projects
Repo: read View project
Repo: write View and manage project, accept/deny UI tests, review pull requests
If your project is hosted in Bitbucket, ensure that you and your team members have the contributor role.

Add collaborators

Chromatic syncs permissions with your Git provider for linked projects. You can add a collaborator by sharing access with them in your Git provider.

For unlinked projects, share the invite link with your collaborator. When they login they will automatically be added to your project.

Remove collaborators

If the project is linked to a online repository, once you remove the collaborator from the repository, your collaborator’s list will be automatically updated in Chromatic.

For unlinked projects, contact us via our in-app chat.

Why can't my teammates access a project?

Chromatic syncs permissions at the account and repo level. Check that your teammates are listed as collaborators in your GitHub, GitLab, or Bitbucket repository.

If they aren’t listed, please add them and try accessing the Chromatic project again (you may have to re-login). Learn more aboutaccess control.


In Chromatic there two types of projects:

  1. Linked projects, where access is linked to a project/repository on either GitHub, GitLab or Bitbucket (depending on which service you used to log in to Chromatic).
  2. Unlinked projects, where access is controlled via an invite list

Linked Projects

When you link a project to an online repository (on the “Manage” page, or when creating it), we synchronize access to the project with the permissions on the relevant service. There are two levels of access:

  • Viewer: users can view snapshots and builds, but cannot review
  • Reviewer: users can review snapshots and manage other aspects of the project.

Note that public repositories on GitHub/GitLab/Bitbucket give viewer access to all users. A user must be granted explicit contributor access by a maintainer to become a reviewer in Chromatic. For private repositories, anyone who has access to the repository in GitHub/GitLab/Bitbucket will have reviewer access in Chromatic.

Unlinked Projects

To grant access to a unlinked project that you’ve created, either link it to a third-party repository, or use the invitation URL accessible on the “Manage” page.

Users that have used the invitation link will get reviewer access to the project.

We're actively working in improving on how access control is implemented in Chromatic. Keep checking in for updates.