Access control

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 repositories, set PR statuses, and retrieve users for assignment to review. Chromatic will never read/write source code.

For Enterprise customers using GitHub Enterprise Server and GitLab self-managed, the same scopes are required.

To link a project to a Git provider repository, you need:

• Membership in the organization that owns the repository.
• Write access to the repository, via one of the following roles:

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

No, Chromatic only uses the static Storybook build or Storybook source code (if the static build is not being used). The static build refers to a static web application that is generated from your Storybook that can be hosted by any web server.

For unlinked projects: Chromatic does not have access to your git provider

For linked projects: Chromatic requests data from your git provider without accessing your source code.

For GitHub, Chromatic only has access to repository metadata and merge request information.

However, GitLab and Bitbucket don’t offer repository metadata and merge request information without full API access. Therefore, Chromatic has permission to access the source code on GitLab, but it doesn’t actually access it.

Chromatic requests the minimum permissions needed to use the tool. With GitHub, we request permissions for “OAuth” and “GitHub app” respectively. This allows organizations to expand permissions incrementally as they use more features.

If your GitHub organization requires an admin to approve apps, you’ll need to request access inside of Chromatic and track their status inside of GitHub (below).

1. Chromatic OAuth app: Enables GitHub sign-in. Track your access request here.
2. Chromatic.com app: Enables UI Review. Track your access request here.

No, Chromatic doesn’t support custom GitHub roles.

Chromatic only receives the role name from GitHub, not the specific permissions associated with it. Custom role names prevent Chromatic from accurately determining permissions.

When you have a fork of a private organization owned repository, that forked repository is going to be subject to that organization’s access restrictions. For example, org1/my-repo is the original repository and you fork it to org2/my-repo. In this situation, the original repo org1/my-repo would need to approve Chromatic’s OAuth App on their end. Once they do, you’ll be able to use the forked repo org2/my-repo with Chromatic.

If you encounter an <unknown> project, this means Chromatic can no longer connect it to your Git repository.

To refresh the Git access token and reconnect the <unknown> project, request one of the account owners to log out and log back into Chromatic.

Alternatively, replace the Git token from the Configure tab on the Manage page of your project.

In the Project’s Manage tab, you may see that your repository details couldn’t be synced due to the token. This typically occurs for one of two reasons:

1. For GitHub, an access token is required when you first set up your project to link Chromatic to your repository. If this step wasn’t completed, the token will be missing.

2. Tokens can expire or be deleted on your Git provider’s side, which revokes their permissions.

Another team member can replace the token, or you can unlink and relink the repository to fix the issue. If this doesn’t help, contact us at support@chromatic.com or via our in-app live chat.

If IP restrictions are set on your Git provider account but you haven’t added Chromatic’s IPs to the allowlist, the token may show as invalid or missing too. Setting the IPs will resolve this specific case.

Using a dedicated service user (or “bot user”) for your Chromatic integration with git providers ensures greater stability, security, and control for your team’s workflows. Benefits:

• Integrations won’t break if an individual team member leaves the company or has their access changed, since the token isn’t tied to a personal account. Access changes can lead to tokens being missing or invalid.

• It helps meet company policies that prohibit the use of personal tokens for external service integrations and comply with the principle of least privilege.

• Access is managed through a dedicated account, providing better oversight and control than when scattered personal access tokens (PATs) are used for different Chromatic projects.

If your project is part of an organization, you need to have your access request approved by an admin at the organization level. Approval from a repository-level admin alone will not be sufficient. The actual scopes that Chromatic requires are listed here.

For linked accounts

To migrate your Chromatic projects to the new Git provider:

1. Connect your user account to the new git provider via the Profile page. Under “Connected accounts,” link your new git provider. Ensure that everyone on your team does the same. Warning: do not disconnect the old git provider yet since you may lose access.

2. In the upper-right corner of the dashboard, open the menu and click “Add” to create a new Chromatic organization account for your new Git provider. You’ll now see both accounts in that list, each linked to different Git providers.

3. Unlink all existing projects from the old Git provider through the Manage tab.

4. Then link all projects to repositories from the new Git provider. Note that projects will automatically move to the new Chromatic organization level account.

If you have a paid account, use our in-app chat to get in touch, or email us at support@chromatic.com to move your subscription to the new Chromatic entity.

For unlinked accounts

Follow steps 1, 3, and 4 from the guide above, but you don’t need to create a new Chromatic organization level account.

Important

Connecting one Chromatic entity to multiple Git providers is not yet supported.

• ❌ You can’t create unlinked projects on GitHub org, Bitbucket workspace, or GitLab group connected accounts.
• ✅ You can create unlinked projects on personal GitHub, Bitbucket, or GitLab accounts.
• ✅ You can create unlinked projects on email/password accounts.

If your account is currently connected to a GitHub org, Bitbucket workspace, or GitLab group, you’ll need to create a new email/password account to set up an unlinked project. Your teammates can access this account by sharing credentials (for example, with a password manager).

To share billing between an existing connected account and an email/password account, message us via in-app chat.

Email accounts are not connected to a Git provider by default. This means you can only create unlinked projects.

Follow these instructions to link your project to a Git provider:

1. Go to your profile (/profile) and connect to your Git provider.
2. Go to the project’s Manage page » Collaborate tab.
3. Click to “sync collaborators with a Git repository”.

This connects your Chromatic email/password account with your Git provider account, allowing you to set up a linked project.

Note: Your personal account must have access to the repository in order to connect in Chromatic. You may need to ask an administrator to grant you additional permissions.

This error can occur when Chromatic isn’t authorized for a GitHub organization that has SSO/SAML also configured. In order to grant access to a project, Chromatic uses that project’s token and your account’s GitHub token. During the login process for Chromatic you authenticate with GitHub and will be presented with a prompt inside of GitHub to authorize Chromatic for use in your organization.

You must click the Authorize button. If you don’t click the Authorize button, but instead click the Continue button, you will not be able to access the project in Chromatic. If the person that set up the project previously logged into Chromatic with their GitHub credential but never authorized Chromatic for their organization, their teammates will also encounter this issue.