Overview

Workspaces with a Gatsby Cloud Enterprise plan can import and build sites from repositories on self-hosted Git servers. Gatsby Cloud currently supports connections to servers running GitHub Enterprise Server.

The following guide will walk through the process of:

• Connecting a GitHub Enterprise Server instance to your Gatsby Cloud workspace
• Importing a Gatsby site from a GitHub Enterprise Server
• Removing a connection with a GitHub Enterprise Server
• Troubleshooting connections with a GitHub Enterprise Server

Connecting a GitHub Enterprise Server instance to your Gatsby Cloud workspace

Overview:

• Create a GitHub App on your GitHub Enterprise Server
• Connect your GitHub App to Gatsby Cloud

1. Create a GitHub App on your Github Enterprise Server

The first step to enabling Gatsby Cloud to interact with your GitHub Enterprise Server will be to create a GitHub App. GitHub Apps enable third parties like Gatsby Cloud to communicate with resources inside your GitHub organization.

Overview:

• Retrieve workspace-specific values from the Self Hosted Git Connection modal
• From your GitHub Enterprise Server, create a new GitHub App
• Configure your GitHub App using the workspace-specific values and update the permissions detailed below
• Generate and store your App’s client secret and private key

A. Retrieve workspace-specific values from the Self Hosted Git Connection modal

To create a GitHub App, you will first need some values that are specific to your Gatsby Cloud workspace. To find these values:

• Go to User Settings from the dropdown on the top right of any page
• Under Workspaces and Billing, select the workspace you’d like to connect to your GitHub Enterprise instance
• From the Self Hosted Git Connection heading, select Add New

You will open a modal that provides the values you will need to create your GitHub App. It should look similar to the example below:

B. From your GitHub Enterprise Server, create a new GitHub App

You can now create a new GitHub App using the values provided in the modal. To create a new GitHub App, login to your GitHub Enterprise Server, then:

• Select Settings from the top dropdown
• Select Developer Settings from the menu
• Select New GitHub App
  • For more details on creating a GitHub App, see GitHub’s documentation.

C. Configure your GitHub App using the workspace-specific values and permissions below

From the Register new GitHub App page, fill in the information as follows:

• GitHub App name: This can be anything; we suggest something clear to users of your team, like Gatsby Cloud Enterprise App

• Homepage URL: We suggest using the URL to your app or website.

• User authorization callback URL: Provided in your connection modal

• Setup URL:  Provided in your connection modal

  • Redirect on update: Select true

• Webhook URL: Provided in your connection modal

• Webhook secret: Generate a random string with high entropy. For more details on how to create a webhook secret, see Securing your webhooks.

  • Note: Make sure to save your webhook secret somewhere secure. You will need to use it in a later step.

• Visual Example of Configuration Settings:

  

⚠️ Note: DO NOT REQUEST USER AUTHORIZATION DURING INSTALLATION

Under Callback URL, the box should be unchecked:

• Enable the following permissions for your app:

  Repository Permissions

  • Checks: Read & write

  • Contents: Read-only

  • Issues: Read & write

  • Metadata: Read-only

  • Pull requests: Read & write

  • Commit statuses: Read & write

  • Visual Example of Repository Permissions

    

  User permissions

  • Email addresses: Read-only

  • Visual Example of user permissions

    

  Subscribe to Events

  • Create

  • Delete

  • Check suite

  • Check run

  • Issue comment

  • Pull request

  • Pull request review

  • Pull request review comment

  • Push

  • Visual Example of Subscribe to events

    

Once you’ve configured your app with the above settings, click the Create GitHub App button at the bottom of the page.

D. Generate and store your App’s client secret and private key

After you’ve created your GitHub App, you can generate a client secret and private key. Store both of these values somewhere, as you will need them for a later step.

To generate a client secret:

• From your GitHub App’s Settings page, find the Client Secrets heading, then select Generate a new client secret
• Write down or copy your generated secret somewhere secure.

To generate a private key:

• From your GitHub App’s Settings page, find the Private Keys ****heading, then select Generate a private key
• Download the generated key and store it securely. You will use this key in a later step.

2. Connect your GitHub App to Gatsby Cloud

Now that you’ve created a new GitHub App on your GitHub Enterprise Server, you will create a connection between your Gatsby Cloud workspace and the GitHub App.

You should already have your connection modal open from the previous step, but if you need to open it again:

• Go to User Settings from the dropdown on the top right of any page
• Under Workspaces and Billing, select the workspace you’d like to connect to your GitHub Enterprise instance
• From the Self Hosted Git Connection heading, select Add New

Under the section Connect your custom GitHub app to Gatsby Cloud, you will now enter the values from your GitHub app:

• Connection Name: This will be the display name we use to refer to your Git connection in Gatsby Cloud. You can enter any name; keep in mind that all members of your workspace will see the Git connection as the name you select.
• Instance URL: The URL where your self-hosted GitHub instance can be accessed. Example: https://my-self-hosted.com - we currently do not support ip addresses, this must be a valid domain leading to your Enterprise GitHub Server that can be accessed
• App ID and Client ID: These are found at the top of your Github Apps setting’s page (shown below):

• Client secret: Enter the client secret for your GitHub app, generated in the previous step.
• Private key: The text contained inside the PEM file that was downloaded in the previous step. 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 into the modal.
• Webhook secret: Enter the webhook secret that you generated in the previous step. This should match the webhook secret that you entered when creating your GitHub App.

After you’ve entered these values, click Save. The new connection will appear under the Self-hosted Git Connections heading.

Importing a Gatsby site from a GitHub Enterprise Server

Overview:

• Select Add Site from your Workspace dashboard
• Under Import from a Git Repository, click the name of the GitHub Enterprise Server you’ve added
• Login to the GitHub Enterprise Server and install the GitHub App to the organization that contains the repositories you’d like to import

Once you’ve added a Self-hosted Git Connection to your workspace, all members of your workspace will see the connection as an option when importing from a Git repository. In the example below, you see the instance named ‘Gatsby Cloud’ appear under the Self Hosted heading:

To import a Gatsby site from your GitHub Enterprise Server, follow these steps:

• Select the connection under the Self Hosted heading
• You will be prompted to login to the GitHub Enterprise Server instance, if you aren’t logged in already
• After you’ve logged in, you will see a prompt to install the GitHub App to an organization in your Github instance (shown below). Follow the “Click here to continue” link to complete the installation.

• In the window that appears, select which organization you’d like to install the GitHub App, and which repositories the app will be allowed to access. Then click Install.

• You will be redirected back to Gatsby Cloud, and the repositories you selected will appear as options to import. From there, you can import and create your site.

Removing a connection with a GitHub Enterprise Server

To remove a Workspace’s connection to a GitHub Enterprise Server, go to your Workspace Settings page:

• Go to User Settings from the dropdown on the top right of any page
• Under Workspaces and Billing, select the workspace that is connected to the GitHub Enterprise Server
• Under Self-hosted Git Connection, find the connection you’d like to remove, and click the Delete button
• Confirm that you want to remove the connection by entering the name of the connection in the prompt.

After you delete a self-hosted Git connection, the connection will no longer appear on the Import a Site page. Any sites that you previously created from repositories in the self-hosted Git server will still be available in Gatsby Cloud. However, you will not be able to trigger new builds or previews for the site.

Troubleshooting a connection with a self hosted Git connection

Here are some suggestions if you run into any issues with using a self hosted Git connection.

Problems with adding a new self hosted Git connection

When you try to add a new self hosted Git connection, we make a test request to the server to validate you’ve entered the following values correctly:

• App ID
• Instance URL
• Private Key

If you see an error message in the modal when trying to add a new connection, please ensure that you’ve entered these values correctly.

Problems with importing a site from a self hosted Git connection

Entering invalid values when creating your GitHub App or adding a Self Hosted Connection can result in a number of possible issues, including:

• Being stuck when trying to authorize with the GitHub Enterprise Server
• Being stuck when trying to install the GitHub App to an organization’s repositories
• Error when building a site from a self hosted Git repository
• Site not building when changes are committed to the site’s repository

When encountering errors, begin by following these steps:

• In Gatsby Cloud, go to Workspace Settings > Self Hosted Git Connection, and click Add New to open the connection modal
• View your GitHub App settings under Settings > Developer Settings
• Ensure that the workspace-specific values in the Self Hosted Git Connection modal have been correctly entered into your GitHub App

If you continue to experience errors, you may need to re-establish a connection between your GitHub App and Gatsby Cloud. To do so:

• From your GitHub App settings, select Revoke All User Tokens.
• From the same page, select Install App in the left navigation.
• Select the GitHub App.
• At the bottom of the page, select Uninstall App. This will uninstall the app from your repositories.
• In Gatsby Cloud, go to Workspace Settings > Self Hosted Git Connection, and delete the existing connection.
• Re-add the connection with the correct values

If you continue to experience issues, then don’t hesitate to Contact Us with a description of what you’re experiencing.