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.

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.

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.

OneLogin, Okta, Google Workspace, PingOne, Keycloak, SimpleSAMLphp-based Identity Providers, and Active Directory Federation Services.

If your provider is not on the list, please reach out to us at support@chromatic.com or use our in-app chat, and we will determine if it is possible to integrate with it.

• ❌ 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.

For Enterprise plans, we support connecting on-premise versions of GitHub Enterprise and GitLab. Please reach out to us via Support to get access.

You also need to have some information from your Git Provider setup ready

1. The URL to your Git Provider (e.g. https://chromatic.github.com, https://gitlab.custom.com)
2. The Name of Your Repository (e.g. chromatic/ux)
3. Access Token (See docs for GitHub and GitLab)

Depending on your Git Provider, the relevant docs for creating an access token can be found below. When you create your token, please ensure that you enable the proper scopes.

Once you have access and the prerequisite details, follow these instructions to link your project to GitHub Enterprise Server or GitLab self-managed:

1. Go to the manage (/manage) page for the app that you want to connect.
2. Click the Configure tab.
3. In the Connected Application section, find the “Sync project with a Git repository” area and click “Add on-prem Git Provider” to enter the details for your repository.

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.