Repository permissions and linking
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.
Self-hosted Git
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 using 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, stated when you install the app, and in the GitHub App settings panel.
- No deploy keys or webhooks. GitHub App 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 on 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.
During installation, you can choose to grant the app access to all repositories belonging to your GitHub user or organization, or to specific repositories only.
If you don’t get this install prompt, the app has already been installed on your GitHub account or on a GitHub organization you belong to. You can confirm that the app is installed and has the correct permissions by checking your Installed GitHub Apps.
If you don’t find the repository or organization you need, 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.
# Install on an existing site
If you created a site using a Deploy to Netlify button or using the older OAuth app authentication, you will need to manually install the Netlify GitHub App.
You can install the Netlify GitHub App through the Netlify UI. On the Site overview page, select Install in the Install the Netlify GitHub App section.
During installation, you can choose to grant the app access to all repositories belonging to your GitHub user or organization, or to specific repositories only.
You can confirm that the app was installed successfully and has the correct permissions by checking your Installed GitHub Apps.
If the Install the Netlify GitHub App section isn’t available in the Netlify UI and the app isn’t included in your Installed GitHub Apps list, you can also unlink and relink your repository to launch the app install process. Start the repository unlink and relink process at Site settings > Build & deploy > Continuous deployment > Repository. Select Manage repository, then Link to a different repository.
# Change the app’s repository access
Once installed, you can configure the Netlify GitHub App at any time to add or remove access to repositories.
If you grant the app access to all repositories owned by your GitHub user or organization, all future repositories and all new sites linked to these repositories will use the app automatically.
# Troubleshoot repository linking
If you can’t find the repository or organization you’re searching for as you go through the repository linking process, this is likely because you didn’t grant access to that resource during the Netlify GitHub App installation.
To grant the Netlify GitHub App access to a repository:
- While linking a repository, in the empty repository selection list, select Configure Netlify on GitHub or Configure Netlify on your self-hosted GitHub to install the app for the desired organization and configure the app’s repository access.
- You can also go directly to your GitHub Apps settings to configure repository access for the installed app. For GitHub Enterprise Server accounts, you can install the app in a similar manner.
# Link a Git repository
You can link a site to a Git repository in the Netlify UI. To do so, go to Site settings > Build & deploy > Continuous deployment > Repository and select Link repository.
When you link a site to a Git repository, Netlify automatically sets up continuous deployment for that site.
Tip
You can stop builds if you don’t want your site to be built when changes are pushed to the linked repository.
# Change linked Git repository
To change which repository is linked to your site, go to Site settings > Build & deploy > Continuous deployment > Repository, select Manage repository, then Link to a different repository.
# Unlink a Git repository
You can unlink a site’s Git repository, which can be useful for troubleshooting, deploying with drag and drop, and disabling continuous deployment.
Unlinking a repository breaks continuous deployment settings. While the site is unlinked, you will only be able to publish new deploys manually using the CLI, API, or drag and drop. In addition, when you unlink a repository the following are deleted:
- Environment variables set in the Netlify UI
- Deploy keys
- Build hooks
To unlink a repository from an existing site, go to Site settings > Build & deploy > Continuous deployment > Repository, select Manage repository, then Unlink the current 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.
# Git submodules
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 using 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, git@github.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.
# Deploy keys
Submodule repositories linked in ssh format, including all private submodule repositories, require an SSH key called a deploy key (in GitHub and in GitLab) or access key (in Bitbucket).
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 Site 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.
# npm packages
You can reference public or private repositories formatted as npm packages in your package.json file dependencies. 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:
"package-name": "git+https://<github_token>:x-oauth-basic@github.com/<user>/<repo>.git"
For GitHub Enterprise Server, create a GitHub personal access token with read-only access, and include it in the package URL as follows:
"package-name": "git+https://<github_token>:x-oauth-basic@<self-hosted-instance.url>/<user>/<repo>.git"
For GitLab, create a GitLab deploy token with read_repository access, and include it in the package URL as follows:
"package-name": "git+https://<token-username>:<token>@gitlab.com/<user>/<repo>.git"
For GitLab self-managed, create a GitLab deploy token with read_repository access, and include it in the package URL as follows:
"package-name": "git+https://<token-username>:<token>@<self-hosted-instance.url>/<user>/<repo>.git"
For Bitbucket, create a Bitbucket app password with read-only access, and include it in the package URL as follows:
"package-name": "git+https://<user>:<app-password>@bitbucket.org/<user>/<repo>.git"
Keep tokens private
You can avoid committing access tokens in public repositories by storing them as environment variables in your site or team settings.
# Community resources
To get help or join the discussion, visit our Forums for a verified Support Guide on accessing other repositories in the build environment.
Did you find this doc useful?
Your feedback helps us improve our docs.