When you link a site to a Git repository, Netlify must gain permission to access your repository code. We may also require permission if you need to access other repositories during your site build.
Git provider permissions
Netlify's method for obtaining permission varies by Git provider. For all sites connected to GitLab and Bitbucket, as well as some existing sites connected to GitHub, we use the Git provider's OAuth2 authentication to obtain a client token to store in your browser.
For all new sites connected to GitHub, we use the Netlify GitHub app. The next section explains the advantages of using the Netlify GitHub app, along with instructions for converting an existing site to use the newer app.
If you want to link a site to a self-hosted GitHub or GitLab repository, you will need to make a custom GitHub Enterprise Server app or GitLab self-managed OAuth app for your self-hosted instance. Visit the self-hosted Git doc to get started.
Authentication with the Netlify GitHub app
When you create a new site from a GitHub repository, Netlify obtains permission to do this by installing the Netlify GitHub App on your GitHub account. For self-hosted GitHub repositories, Netlify obtains permission by installing your custom GitHub App on your GitHub Enterprise Server account.
Authenticating via a GitHub App offers many advantages over traditional OAuth Apps on GitHub, including:
- Scoped repository access. You can choose to grant access to all repositories belonging to your GitHub user or organization, or to specific repositories only. There is no need for special organization-level settings as was previously required for OAuth apps.
- Finer-grained permissions. This allows Netlify to request only the permissions we need, clearly stated when you install the app, and in the GitHub app settings panel.
- No deploy keys or webhooks. GitHub Apps installations automatically create outgoing webhooks as needed, and handle repository access with generated, limited-scope tokens that expire after one hour for increased security.
- Better comment notifications. Integrations like our pull request comment notifications can be sent directly by the Netlify GitHub App, without the need for a personal user access token.
- GitHub checks. GitHub Apps have access to GitHub's checks API, which enables you to receive rich deploy summary information in your GitHub pull requests and commit lists.
Install with a new site
When you create a new Netlify site from Git, and select GitHub as your Git provider, you will be prompted to install the Netlify GitHub App if you haven’t already.
If you do not see this prompt, the app has already been installed on your GitHub account or on a GitHub organization you belong to. If you don’t see the repository or organization you’re looking for, this is likely because you have not granted access to it. Check our guidance on troubleshooting repository linking to learn how you can adjust organization/repository access.
Convert existing sites
All new GitHub.com-connected sites on Netlify will use the Netlify GitHub App automatically, but some existing sites may still be using the older OAuth App authentication.
You can manually upgrade to using the GitHub App on an existing site from the site dashboard at Settings > Build & deploy > Continuous deployment > Build settings. Select Edit settings, then Link to a different repository. This will take you through the repository selection process, and prompt you to install the app.
If you already have the app installed on your GitHub.com user or organization, you can automatically upgrade your existing sites by configuring your integration to grant access to their connected repositories. If you grant access to your entire user or organization, all current and future sites will use the GitHub App automatically.
Troubleshoot repository linking
If you can’t find the repository or organization you’re searching for in the repository selection list, this is likely because you have not granted access to that resource in the Netlify GitHub App installation.
- If you're using GitHub.com
- Select Configure Netlify on GitHub in the repository selection list to install the app on the desired organization and/or configure the app's repository access.
- You can also go directly to your GitHub Apps settings to configure repository access for the installed app.
- If you're using GitHub Enterprise Server
- Select Configure Netlify on your self-hosted GitHub in the repository selection list to install the app on the desired organization and/or configure the app's repository access.
- You can also go directly to your GitHub Enterprise Server Apps settings to install the app on the desired organization and/or configure the app's repository access.
Change linked repository
Once a site is linked to a repository, it must stay linked to a repository.
You can stop builds if you don't want your site to be built when changes are pushed to the linked repository.
To change which repository is linked to your site, go to Settings > Build & deploy > Continuous deployment > Build settings, select Edit settings, then Link to a different repository.
Access other repositories at build
If you need to fetch contents from other repositories, public or private, you'll need to make some accommodation for this. The two most common methods for accessing other repositories during the build are Git submodules and npm packages.
To include an outside repository as a subdirectory in your own repository, always configure it as a submodule. If you do not, it may work locally via cloning, but the sub-repository content will not be pushed to your Git provider, and it will not be available to your build on Netlify.
If a submodule repository is public, you can use
https format (for example,
https://github.com/owner/project) to link it in your submodule configuration. If the repository is private, or if you prefer to use
ssh format (for example,
email@example.com:owner/project.git), you will need to follow the instructions below to generate a deploy key in Netlify and add it to the submodule repository settings.
SSH keys are actually a pair of keys: one private, and one public. To generate a new key pair for a Netlify site, go to Settings > Build & deploy > Continuous deployment > Deploy key, and select Generate public key. Netlify will store the private key, and provide the public key for you to add to the repository settings for your submodule.
You can reference public or private repositories formatted as npm packages in your
package.json file. Private repository modules require a special link syntax that varies by Git provider.
For GitHub, create a GitHub personal access token with read-only access, and include it in the package URL as follows:
For GitHub Enterprise Server, create a GitHub personal access token with read-only access, and include it in the package URL as follows:
For GitLab, create a GitLab deploy token with
read_repository access, and include it in the package URL as follows:
For GitLab self-managed, create a GitLab deploy token with
read_repository access, and include it in the package URL as follows:
For Bitbucket, create a Bitbucket app password with read-only access, and include it in the package URL as follows:
Keep tokens private
You can avoid committing access tokens in public repositories by storing them as environment variables in your site or team settings.
For more details about accessing other repositories at build, and to get help, visit the related topic in Netlify Community.
Did you find this doc useful?
Your feedback helps us improve our docs.