Setup a self-hosted GitLab

Owned by Fatima Idrissi (Deactivated)
Last updated: Mar 13, 2020
3 min read

Please follow this guide if you want to connect your Living Documentation with a self-hosted GitLab repository

Prerequisites

  • GitLab Server admin account

  • Jira admin account

Instructions

  1. Create a new OAuth application in GitLab

  2. Open your firewall to Cucumber for Jira servers

  3. Create a new provider in Cucumber for Jira settings

  4. Create a Living Documentation using the new provider

Create a new OAuth application in GitLab

Detailed documentation on how to set up an OAuth application in GitLab can be found here

Visit https://<your-gitlab-server>/admin/applications

Click on New application

  1. Choose a name: Cucumber for Jira for example

  2. Fill in the Redirect URI field with the following URL: https://c4j.cucumber.io/oauth/gitlab/callbacks

  3. Check the following scopes:

    • api

    • read_repository

  4. Click on Submit

Now you should have your newly created OAuth application. You will need the Client ID and the Client secret for the next steps.

Open your firewalls to Cucumber for Jira servers

You can skip this section if your GitLab server is publicly available on the internet

Cucumber for Jira is a cloud application, this means our servers need to be able to communicate with your self-hosted GitLab instance through HTTP protocol.

Your network team should configure your company firewall rules to allow HTTP(S) traffic from these IP ranges used for outgoing traffic:

  • 5.104.96.0 - 5.104.103.255 (5.104.96.0/21)

  • 46.231.144.0 - 46.231.151.255 (46.231.144.0/21)

  • 109.232.232.0 - 109.232.239.255 (109.232.232.0/21)

  • 185.21.192.0 - 185.21.195.255 (185.21.192.0/22)

  • 171.33.64.0 - 171.33.127.255 (171.33.64.0/18)

  • 148.253.64.0 - 148.253.127.255 (148.253.64.0/18)

This information comes from our provider wiki page and might be out of date. Most up-to-date information is available here.

Create a new provider in Cucumber for Jira settings

You need to have Jira admin privileges to create a new provider

Go to Jira settings, click on App tab, then choose Set up a private Git host from Cucumber for Jira section

The first step is to verify that your GitLab Server API is accessible from our servers.

Type the API base URL in the text field and click on Verify

If the verification succeeds, a form will be shown to provide the OAuth information:

An error message will be shown instead.

The required fields are:

  • Name: A name for your GitLab Server (it can be anything you like)

  • OAuth base URL: https://<gitlab_server_url> , where <gitlab_server_url> is the URL of the GitLab Server instance

  • Client ID: is the Application ID that was shown when the OAuth application was created

  • Client secret: is the Secret that was shown when the OAuth application was created

After filling the OAuth form, click on Complete setup. A confirmation is shown once the setup is completed.

Create a Living Documentation using the new provider

Now that everything is set up. You should be able to see the new provider in the Living Documentation creation screen

The workflow is the same as Cloud providers