Self-hosted Git

This feature may not be available on all plans.

You can connect your Netlify team to your GitHub Enterprise Server and/or GitLab self-managed instance to make linking your sites to your self-hosted repositories easier. Teams connected to self-hosted Git instances can select self-hosted repos in the Netlify UI when creating a new site from Git or changing a site's linked repository.

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 via Netlify CLI, including:

Overview

Self-hosted Git information and settings are found under Team settings > General > Self-hosted Git

The default state indicates that both GitHub Enterprise Server and GitLab self-managed are "Not connected"

Connecting your Netlify team to your self-hosted GitHub/GitLab 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. Your self-hosted Git instance must be available outside of your VPN/Firewall.
  • 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 Collaborator can select the self-hosted instance when choosing the Git provider where a site’s source code is hosted.

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 both a GitHub Enterprise Server instance and a GitLab self-managed instance, 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.

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.

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
    • 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:
    • Delete
    • Pull request
    • 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: The URL where your self-hosted GitHub instance can be accessed.
    • App ID, Client ID, and Client secret: These are assigned to your GitHub App by GitHub and can be found in the app's settings under General > About.
    • Private key: The 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: Enter 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 creating a new site from Git or when changing the linked repository for an existing site. The first time you do this, you will be prompted to install your GitHub App as described in our docs about repository permissions and linking.

Troubleshooting

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.
  • 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.
  • 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 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 via webhooks:

GitLab self-managed

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

Requirements

  • Self-hosted GitLab instance. You can use the Community Edition or the Enterprise Edition hosted either on premises or in the cloud.
  • GitLab API v4. This means you need GitLab version 8.17 or above.

Setup

To connect your Netlify team to GitLab self-managed, you will need to create a GitLab OAuth application on your self-hosted instance and then provide us details about your instance and app.

Create OAuth application

You can visit GitLab's docs on OAuth applications for more information about OAuth application settings and options. You can create your OAuth application through your user profile or in your instance's admin area. We recommend creating it in the admin area where other admin users will have access to manage the settings.

  1. In your GitLab self-managed instance, go to the Admin Area (represented by a wrench icon), navigate to Applications, and then select New application.
  2. Fill in the New application settings as follows:
    • Name: Netlify
    • Redirect URI: https://api.netlify.com/auth/done
    • Scopes: api
  3. Select Submit.

After you create your application, GitLab will provide you an Application ID and Secret. You'll need to give these to Netlify in the next part of the setup.

Connect to GitLab self-managed from Netlify

  1. Go to Team settings > General > Self-hosted Git, select Edit settings, then select Connect for GitLab self-managed. This will open a configuration modal that contains a form to provide us the necessary details about your instance and app.
  2. Provide the following details about your GitLab instance and OAuth application:
    • Instance URL: The URL where your self-hosted GitLab instance can be accessed.
    • Application ID and Secret: These are assigned to your OAuth application by GitLab and can be found in your application's details. These will be used to authenticate requests made by Netlify to your self-hosted GitLab instance.
  3. Select Save.

After you complete the setup for GitLab self-managed, your team will be able to select your self-hosted instance when creating a new site from Git or when changing the linked repository on an existing site.

Troubleshooting

If you're having trouble saving your GitLab self-managed settings in Netlify:

  • Verify that your self-hosted GitLab instance is accessible outside of your VPN/firewall.
  • Verify that the Application ID and Secret match the values assigned by GitLab to your OAuth application. These can be found in your application's details.

If you need to change your GitLab self-managed 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 GitLab instance.

If GitLab serves an authorization error saying The redirect URI included is not valid:

  • Verify that your GitLab OAuth application has Redirect URI set to https://api.netlify.com/auth/done.

If Netlify serves an authorization error saying No Auth Provider Found:

  • Your GitLab OAuth application may have been changed. You won't be able to compare your GitLab self-managed settings on Netlify to your OAuth application's current state since you can't edit the 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 GitLab OAuth application.

If you're having trouble linking your sites to your self-hosted repositories:

  • Your GitLab self-managed instance may have become inaccessible. Verify that your self-hosted GitLab instance is accessible outside of your VPN/firewall.