Access control

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


Sign up via OAuth or email. Chromatic supports the cloud versions of GitHub, GitLab, or Bitbucket on 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, we recommend signing up via email. 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 sign in. 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


A Chromatic organization mirrors its counterpart GitHub Organization, Bitbucket Group, or GitLab Team. Open the account menu to swap between organizations or add a new organization.

Account menu


There two types of Chromatic projects: linked and unlinked.

Linked projects

Linked projects are associated with a repository on GitHub, Bitbucket, or GitLab. That allows Chromatic to sync collaborators, badge pull requests, get pull request metadata for UI Review, and keep track of UI Test baselines.

You can link a project during the project creation process or afterward on the project’s Manage page.

Unlinked projects

Unlinked projects are not linked to a repository on GitHub, Bitbucket, or GitLab. They do not automatically sync collaborators or badge pull requests. An unlinked project is perfect for teams that self-host Git or have enterprise Git providers (that aren’t on Chromatic’s enterprise plan).

The characteristics of an unlinked project include:

  • Chromatic runs as a CI-only job.
  • Collaborators are manually managed via an invite list.
  • PR badging is manually configured in your CI provider.
  • Notifications are manually setup via Chromatic’s custom webhooks.

Learn how to create an unlinked project here.