Note: Some UI updates may happen on different versions of your GitLab Self Managed server so the interface may look different in some cases

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 and GitLab Self Managed Applications.

The following guide will walk through the process of:

• Connecting a GitLab Self Managed Server to your Gatsby Cloud Workspace
• Importing a Gatsby Site from a GitLab Self Managed Server
• Removing a connection with a Gitlab Self Managed Server
• Troubleshooting connections with a GitLab Self Managed Server

Connecting a GitLab Self Managed Server to your Gatsby Cloud workspace

Overview:

• Create an OAuth App on your GitLab Self Managed Server
• Connect your GitLab Server to Gatsby Cloud

1. Create an OAuth App on your GitLab Self Managed Server

The first step to enabling Gatsby Cloud to interact with your GitLab Self Managed Server will be to create an OAuth App. OAuth Apps are used to authorize Gatsby Cloud to act on your behalf in order to interact with resources inside your Self Managed Server in secure ways.

Overview:

• [From Gatsby Cloud] Retrieve workspace-specific values from the Self-Hosted Git Connection Modal
• [From your Self Managed Server] Create a new OAuth App
• [From Your Self Managed Server] Configure your OAuth app using the workspace-specific values and update the permissions detailed below  

A. [From Gatsby Cloud] Retrieve workspace-specific values from the Self-Hosted Git Connection Modal

To create an OAuth App, you will first need the the callback url from the connection modal.

• Go to User Settings from the dropdown on the top of any page
• Under Workspaces and Billing, select the workspace you’d like to connect to your GitLab Self Managed instance
• From the Self Hosted Git Connection heading, select Add New (next to the GitLab Logo)

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

B. [From your Self Managed Server] Create a new OAuth App

You can now create a new OAuth Application using the value for callback URL. To create a new OAuth App, login to your GitLab Self Managed Server, then:

• Select Preferences from the top dropdown (the same one you can use to log out)
• Select Applications from the menu

you should be able to configure your OAuth Application

C. [From Your Self Managed Server] Configure your OAuth app using the workspace-specific values and update the permissions detailed below

From the Applications page, fill in the information as follows:

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

• Redirect URI (later changes to callback URL): add the value from the modal called the callback URL(note, the callback URL value may have changed so please copy the value from the modal and not from the visual above)

• Uncheck the “expire your access tokens checkbox,” Gatsby cloud currently does not support expiring your access tokens

  The values should look something like this:

Below will be some permissions, Gatsby Cloud needs the following permissions:

• api
• read_user
• read_repository
• profile
• email

Your permissions should look something like this:

Click Save Application, and you should have a view like this:

These values will be helpful for step 2.

2. [From Gatsby Cloud] Connect your GitLab Self Managed Server to Gatsby Cloud

Now that you’ve created a new OAuth Application on your GitLab Self Managed Server, you will create a connection between your Gatsby Cloud workspace and the Server.

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

• Go to User Settings from the dropdown on the top 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 (next to the GitLab Logo)

Under the section Connect your custom GitLab Self Managed Server to Gatsby cloud, you will now enter values from your OAuth Application:

• Display 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 GitLab 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 Self Managed Server that can be accessed outside of a firewall
• App ID and Client Secret(or secret in OAuth App): These are found at the top of your OAuth Application setting’s page where you can copy them (shown below):

After you have entered these values, click Save. The new connection will appear under the Self-hosted Git Connections heading(and yes you can add multiple connections from the same provider) and your connection should ask you to authorize:

when you click authorize connection you will be taken to a screen like this(see troubleshooting if you see any other screen) - note: this is a time sensitive screen which means you will be redirected back without authorization if you stay at this screen too long (if this happens you can click the authorize connection button again):

after authorizing, your connection should say connected and you should see the option to add a site like this:

Importing a Gatsby Site from a GitLab Self Managed Server

When you click the Add a Site button, you will be redirected. After you’ve been redirected, you will now have access to all of your repositories:

from there you can import and create your site

Removing a connection with a Gitlab Self Managed Server

To remove a Workspace’s connection to a GitLab Self Managed Server, go to your Workspace Settings page on Gatsby Cloud:

• 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 Self Managed 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, you can only delete them.

Troubleshooting connections with a GitLab Self Managed Server

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

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

When encountering errors, begin by following these steps:

• make sure your server is available outside of your firewall
• In Gatsby Cloud, go to Workspace Settings > Self Hosted Git Connection, and click Add New to open the connection modal
• View your OAuth App settings under Settings > Applications
• Ensure that the workspace-specific values in the Self Hosted Git Connection modal have been correctly entered into your GitHub App

Common issues

• site can’t be reached: you entered the wrong instance url or an invalid url (or firewall is blocking access)

  

• Client Authentication failed - you entered the wrong app Id or client secret - delete your connection and follow the steps above to get the correct values.

  

• The requested scope is invalid: most likely scopes are not correctly defined. make sure the following are correctly checked: api, read_user, read_repository, profile, email

  

• if the authorization didn’t complete, make sure you entered the correct Redirect URI/callback URL from the connection modal in your application settings

• make sure you unchecked the option to `

• one of the simplest solutions with authorization issues may be to delete your connection and enter the values in again

• if you are unable to see your repositories, you may not have the correct permissions, check on your GitLab Self Managed Server

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