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.
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. This 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.
Click Configure Netlify on GitHub or go directly to your GitHub Apps settings to add organizations or repositories to your installation.
Convert existing sites
All new GitHub-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 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 looking for in the repository selection list, this is likely because you have not granted access to that resource in the Netlify GitHub App installation.
In the repository selection list, select Configure Netlify on GitHub or go directly to your GitHub Apps settings to add organizations or repositories to your installation.
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.
- To include an outside repository as a subdirectory in your own repository, always configure it as a submodule. Cloning the sub-repository locally will not make it available to others, including Netlify's buildbot.
- When linking to a public repository, use
httpsformat (for example,
- For private repositories, always use
sshformat references (for example,
firstname.lastname@example.org:owner/project.git). Additionally, you'll have to contact our helpdesk to get a deploy key to complete the setup for your private submodule.
- To access private GitHub repositories directly from your
package.jsonfile, you can use a GitHub access token in the following format:
- To access private GitLab repositories directly from your
package.jsonfile, use GitLab access tokens.
- If you use Bitbucket, you can use an app password in the same way.
For more details and to get help, visit the related topic in Netlify Community.
Did you find this doc useful?
Your feedback helps us improve our docs.