Netlify Docs
Ask Netlify

Contact

Configure & deploy site /Git /

Self-hosted Git

This feature is available on Enterprise plans.

You can connect your Netlify team to your instance of GitHub Enterprise Server, GitLab self-managed, or Bitbucket Data Center and Server to make linking sites to repositories easier.

Supported Git instances

You can connect repositories from your Git provider instance to the Netlify UI in the following ways:

After selecting GitHub when creating a new site for example, you’ll be able to choose between GitHub.com or your self-hosted instance.

Beyond simplifying the initial configuration of continuous deployment, Netlify’s self-hosted Git feature offers several long-term advantages over manual setup using Netlify CLI, including:

# Connect a Netlify team to your Git provider instance

Self-hosted Git information and settings are found under

Team settings General Self-hosted Git
.

The default state indicates that self-managed instances are "Not connected."

Connecting your Netlify team to your self-hosted GitHub, GitLab, or Bitbucket instance requires setup on both Netlify and your self-hosted Git instance. The configuration steps vary by Git provider. Read the general requirements and limitations below before you get started with the provider-specific sections.

# Requirements

  • Instance availability. Our build process must be able to contact your self-hosted Git instance. If your self-hosted Git instance is behind a VPN/firewall, enable Private Connectivity and allowlist the private network IP address.
  • Team member roles. You must be a Team Owner to connect your Netlify team to your self-hosted Git instance. After an Owner sets up the connection, any Team Owner or Developer can select the self-hosted instance when choosing the Git provider where a site’s source code is hosted.
  • Site repository available at a public URL. Netlify sites can only connect to GitHub Enterprise Server or GitLab self-managed repositories that are available at a public URL. This is not a requirement for Bitbucket Data Center and Server. On your Git provider instance, you can configure a single organization or project to allow public repositories.

# Limitations

  • Site transfer. Because sites linked to self-hosted repositories rely on a team-level connection to the self-hosted Git instance, you cannot transfer a site between teams if the site is linked to a self-hosted repo. You can contact Support for assistance with transferring sites linked to self-hosted repos.
  • Number of connections. You can connect your Netlify team to instances of GitHub Enterprise Server, GitLab self-managed, and Bitbucket Data Center and Server, but you cannot connect your team to multiple self-hosted instances of the same Git provider. A GitHub Enterprise Server instance can be connected to only one Netlify team.
  • Sensitive variable policy. Because self-hosted instances enable a higher degree of access control, we treat all self-hosted repositories as private. This means you won’t be able to set a sensitive variable policy for a site linked to a self-hosted repo.
  • Deploy to Netlify button. You cannot create a Deploy to Netlify button for a self-hosted repo.
  • Git Gateway. Self-hosted repositories on an instance of GitHub Enterprise Server, GitLab self-managed, or Bitbucket Data Center and Server are not supported with Git Gateway. You must have a repository available on GitHub.com, GitLab.com, or Bitbucket.org.
  • Private repositories for GitHub or GitLab. Netlify sites can only connect to GitHub Enterprise Server and GitLab self-managed repositories that are available at a public URL. This is not a requirement for Bitbucket Data Center and Server. On your Git provider instance, you can configure a single project or organization to allow public repositories.

# Provider-specific setup instructions

Choose your Git provider for your self-hosted instance:

# GitHub Enterprise Server

Make sure you’ve read the general requirements and limitations above before you proceed with this GitHub-specific section.

# Requirements

  • Self-hosted GitHub instance. You can host your GitHub Enterprise Server instance either on premises or in the cloud.
  • Ability to work with GitHub Apps. You’ll need to create a custom GitHub App as part of the setup. This means you need GitHub Enterprise Server version 2.13 or above. The required GitHub permissions depend on where you want to create and install the app. Visit GitHub’s docs about apps for more information.
  • Hostname configured. You must set a hostname for your appliance, we cannot connect based on a hard-coded IP address.
  • Enterprise policy enabled that allows public repositories. Learn more about GitHub Enterprise Server’s organization policies.

# Setup

To connect your Netlify team to GitHub Enterprise Server, you will need to create a custom GitHub App on your self-hosted instance and then provide us details about your instance and app.

# Get started

Most of the GitHub App settings take universal values that are provided in this documentation. Some require team-specific values that you can find in the Netlify UI.

To get started, go to

Team settings General Self-hosted Git
, select Edit settings, then select Connect for GitHub Enterprise Server.

This will open a configuration modal that contains the team-specific values you’ll need to create your GitHub App, followed by a form to provide us the necessary details about your instance and app.

# Generate webhook secret

You will need to create a unique webhook secret and provide it to both your GitHub App and Netlify. This will be used to verify that webhooks received by Netlify are from your self-hosted GitHub instance.

Visit GitHub’s docs on securing your webhooks to learn how to generate a random string with high entropy to use for your webhook secret. Keep this somewhere secure that you can access later so that you can provide your webhook secret to both your GitHub App and Netlify.

# Create GitHub App

You can visit GitHub’s docs on creating a GitHub App for more information about GitHub App settings and options. You can create your GitHub App under your personal account or an organization. We recommend creating it under an organization where other Organization Owners will have access to manage the settings.

  1. In your GitHub Enterprise Server instance, select your avatar (labeled “View profile and more” for screen readers) and then select Settings.
  2. Under Organization settings, select the organization where you’d like to create the app. You can install the app on additional organizations after you create it.
  3. Navigate to GitHub Apps and select New GitHub App.
  4. Fill in the Register new GitHub App settings as follows:
    • GitHub App name: Netlify
    • Homepage URL: https://app.netlify.com
    • User authorization callback URL: https://api.netlify.com/auth/done
    • Setup URL: enter your team-specific value which takes the form of https://api.netlify.com/github/enterprise/{account_id}/app-installed and can be found in the Netlify UI as described above
    • Redirect on update: true
    • Webhook URL: enter your team-specific value which takes the form of https://api.netlify.com/hooks/github_enterprise/{account_id} and can be found in the Netlify UI as described above
    • Webhook secret: enter the random string with high entropy that you generated as described above
  5. Set Repository permissions as follows:
    • Checks: Read & write
    • Contents: Read-only
    • Issues: Read & write
    • Metadata: Read-only
    • Pull requests: Read & write
    • Commit statuses: Read & write
  6. Set User permissions as follows:
    • Email addresses: Read-only
  7. Under Subscribe to events select the following events:
    • Create
    • Delete
    • Issue comment
    • Pull request
    • Pull request review
    • Pull request review comment
    • Push
  8. Make a selection for Where can this GitHub App be installed?
    • You can choose either option based on how your Netlify team will use organizations to collaborate in your self-hosted GitHub instance.
  9. Select Create GitHub App.

# Generate private key

After you create your GitHub App, you’ll be able to generate a private key. You’ll provide the private key to Netlify along with other details about your instance and app. This will be used to authenticate requests made by Netlify to your self-hosted GitHub instance.

  1. Under the General settings for your GitHub App, select Generate a private key. This will create a private key in PEM file format which will automatically download to your computer.
  2. Keep the PEM file somewhere secure that you can access later so that you can provide your private key to Netlify. GitHub will store only the public portion of the key.

# Provide GitHub instance and app details to Netlify

After you create your GitHub App and generate a private key, you can finish your Self-hosted Git configuration on Netlify in the GitHub Enterprise Server modal that you opened as described above.

  1. Provide the following details about your GitHub instance and app:
    • Instance URL: URL where your self-hosted GitHub instance can be accessed.
    • Clone URL: URL where your self-hosted GitHub instance repositories can be cloned (if different than your Instance URL).
    • App ID, Client ID, and Client secret: values that are assigned to your GitHub App by GitHub and can be found in the app’s settings under General > About.
    • Private key: text contained inside the PEM file that you downloaded as described above. The private key begins with -----BEGIN RSA PRIVATE KEY----- and ends with -----END RSA PRIVATE KEY-----. You can open the PEM file in a text editor to copy the contents.
    • Webhook secret: the random string with high entropy that you generated as described above. This should match the webhook secret that you entered when creating your GitHub App.
  2. Select Save.

After you complete the setup for GitHub Enterprise Server, your team will be able to select your self-hosted instance when importing a new project or when changing the linked repository for an existing site. The first time you select your self-hosted instance, you will be prompted to install your GitHub App as described in our docs about repository permissions and linking.

# Troubleshooting

Here are steps to address issues that you may encounter using GitHub Enterprise Server with Netlify.

# If you’re having trouble saving your GitHub Enterprise Server settings in Netlify

  • Verify that your self-hosted GitHub instance is accessible outside of your VPN/firewall or that you’ve updated your VPN/firewall allowlists for Private Connectivity.
  • Verify that the App ID, Client ID, and Client secret match the values assigned by GitHub to your GitHub App. These can be found in the app’s settings under General > About.
  • Verify that your Private key is entered correctly. It should begin with -----BEGIN RSA PRIVATE KEY----- and end with -----END RSA PRIVATE KEY-----. You can generate a new private key for your GitHub App if necessary.

# If you need to change your GitHub Enterprise Server settings on Netlify

  • You’ll have to delete the old connection and create a new one. This is to protect the sensitive values in the settings.
  • To delete the old connection, go to
    Team settings General Self-hosted Git
    , select Edit settings, and then use the x button next to your self-hosted GitHub instance.

# If you’re having trouble linking your sites to your self-hosted repositories

  • Your GitHub Enterprise Server instance may have become inaccessible. Verify that your self-hosted GitHub instance is accessible outside of your VPN/firewall or that you’ve updated your VPN/firewall allowlists for Private Connectivity.
  • Your GitHub App may have been deleted. Verify that your GitHub App still exists in your GitHub Enterprise Server instance.
  • Your GitHub App may have been changed. You won’t be able to compare your GitHub Enterprise Server settings on Netlify to your app’s current state since you can’t edit the Netlify Self-hosted Git settings once saved. You can delete the old connection as described above and create a new one to make sure you’re matching the current state of your GitHub App.

# If you get errors when triggering a build using webhooks

←