GitHub Permissions

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

Installing the Netlify App on GitHub

New Sites

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.

GitHub's prompt to install the Netlify app, including permissions, and options to select repositories

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.

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 > Deploy 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.

Restrict Access for Organizations

The Netlify app is a first class GitHub App, which means you can choose exactly which repositories Netlify has access to. There is no need for special organization-level settings as was previously required for OAuth apps.

Troubleshooting 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.

Accessing 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.
  • Always use ssh format references to all repositories (git@github.com:owner/project.git instead of https://github.com/owner/project)
  • To access private GitHub repositories directly from package.json, you can use a GitHub access token in the following format: git+https://<github_token>:x-oauth-basic@github.com/<user>/<repo>.git
  • To access private GitLab repositories directly from package.json, use GitLab access tokens.
  • If you use BitBucket, you can use an app password in the same way.

If you have trouble getting these methods working, or cannot use them due to some constraints, contact our helpdesk for further advice and please explain why you cannot use the above methods so we can give you the best advice.


Notice something is incorrect or outdated?

First off, great eye! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.

Want to get started quick?