Connect to a GitLab Enterprise Edition host

This page explains how to connect to a GitLab Enterprise Edition host to Cloud Build.

Before you begin

Enable the Cloud Build and Secret Manager APIs.
Enable the APIs

If you have not installed a GitLab Enterprise Edition Server instance, see the installation guide from GitLab Enterprise Edition for instructions.

Setting up

Before you create a GitLab Enterprise Edition host connection, you must obtain an API key to authenticate and accept incoming events from GitLab Enterprise Edition. Additionally, you must create personal access tokens in GitLab Enterprise Edition to create webhooks and retrieve repository data.

This section discusses steps you need to complete before creating a GitLab Enterprise Edition trigger.

Obtaining an API key

To connect your host repositories and authenticate incoming webhook events, you need an API key.

To obtain an API key:

Open the Credentials page in the Google Cloud console:

Open the Credentials page
Click Create credentials.
Click API Key.

You will see a dialog with your API key created. Take note of your API key.
If you would like to restrict your key for product applications, click Restrict key to complete additional steps to secure your key. Otherwise, click Close.

To learn how to restrict your key, see Applying API key restrictions.

Creating personal access tokens

You must create two personal access tokens in GitLab Enterprise Edition to perform the following tasks:

Create webhooks: create a personal access token with api access.
Retrieve repository data: create a personal access token with read_api access.

After you've created your personal access tokens, temporarily save your token values, for example, in a plain text file. You will then add the tokens to Secret Manager, a credential store that you'll use with Cloud Build, in later steps. The tokens will be used to connect your GitLab Enterprise Edition repository to Cloud Build.

Connecting to a GitLab Enterprise Edition host

Console

To connect your GitLab Enterprise Edition host to Cloud Build using the Google Cloud console:

Open the Manage repositories page in the Google Cloud console:

Open the Manage repositories page
Select a Region from the drop-down menu.

Note: You cannot connect your host when your Region is set to global.
Click Connect Host.
Select GitLab Enterprise Edition.

The Connect host panel appears.

Enter the following information to connect your GitLab Enterprise Edition instance to Cloud Build:
- Name: The name of your host connection.
  
  Note: The Name must be unique within your Google Cloud project location.
- Host url: The host URL of your GitLab Enterprise Edition instance. For example, https://gitlab.example.com.
  
  Note: The host URL must be a domain name, not an IP address.
- Google Cloud API key: The API key used to authenticate your credentials.
- [OPTIONAL] CA Certificate: Your self-signed or private certificate. Your certificate must not exceed 10 KB in size and should be in PEM format (.pem, .cer, or .crt). If this section is left blank, a default set of certificates is used in place.
  
  Note: If you use a self-signed or private certificate, you need to upload the certificate chain, including root certificates, to Cloud Build instead of only leaf certificates.
- Username: Your GitLab Enterprise Edition account username. This account should have maintainer access to the repositories that you want to connect with Cloud Build.
- Read API access token: Your GitLab Enterprise Edition account personal access token with read permissions.
- API access token: Your GitLab Enterprise Edition account personal access token with api permissions on projects and repositories.
- Connection type: Select Public internet if Cloud Build connects to your instance via public internet. Select Private network access if Cloud Build connects your instance through an existing VPC network using Service Directory.
- [OPTIONAL] Service Directory service: If you select Private network access as your Connection type, complete the following steps:
  1. Under Service Directory service, selection the location for your service:
    - In project your-project
    - In another project
    1. If you select In another project, enter the following information:
      - Project: Select your Google Cloud project ID from the drop-down menu.
      - Region: This field pre-selects the region of your connection. The region specified for your service must match the region associated with your connection.
    2. Namespace: Select the namespace of your service.
    3. Service: Select the service name in your namespace.
Click Connect Host.

The Connect Repository panel appears.

After creating a host connection, your personal access tokens and API key are securely stored in Secret Manager. Following host connection, Cloud Build also creates a webhook secret on your behalf. You can view and manage your secrets on the Secret Manager page.

gcloud

To connect your GitLab Enterprise Edition host to Cloud Build using gcloud commands, you must run the gcloud alpha builds enterprise-config gitlab create command in your terminal. Unlike connecting your host using the Google Cloud console, you'll need to manually store your personal access tokens, API key, and webhook secret in Secret Manager before running the following command:

gcloud alpha builds enterprise-config gitlab create
    --name=GITLAB_ENTERPRISE_EDITION_CONFIG_NAME \
    --region=REGION \
    --user-name=USERNAME \
    --host-uri=HOST_URI \
    --api-access-token-secret-version=API_ACCESS_TOKEN_SECRET_VERSION \
    --read-access-token-secret-version=READ_ACCESS_TOKEN_SECRET_VERSION \
    --webhook-secret-secret-version=WEBHOOK_SECRET_SECRET_VERSION \
    --api-key-secret-version=API_KEY_SECRET_VERSION \
    --service-directory-service=SERVICE_DIRECTORY_SERVICE \
    --ssl-ca-file=SSL_CA_FILE

Replace the following:

GITLAB_ENTERPRISE_EDITION_CONFIG_NAME is the name of your GitLab Enterprise Edition configuration.
REGION is the region where your GitLab Enterprise Edition configuration is located.

Note: You cannot connect your host when your region is set to global.
USERNAME is your GitLab Enterprise Edition username.
HOST_URI is the host URI of your GitLab Enterprise Edition.
API_ACCESS_TOKEN_SECRET_VERSION is the resource name of your api access token stored in Secret Manager. The expected format for secrets stored in Secret Manager is projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/${VERSION_NUMBER}. You can specify latest as your version to use the latest version of your secret. This applies to each resource stored in Secret Manager.

Note: You may need to grant the Secret Manager role to your Cloud Build service account, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. To learn more, see Granting Secret Manager role to your service account.
READ_ACCESS_TOKEN_SECRET_VERSION is the resource name of your read access token stored in Secret Manager.
WEBHOOK_SECRET_SECRET_VERSION is the resource name of your of your webhook secret stored in Secret Manager.
API_KEY_SECRET_VERSION is the Google Cloud API key.
[Optional] SERVICE_DIRECTORY_SERVICE is the name of the Service Directory that is used to communicate with your GitLab Enterprise Edition instance.
[Optional] SSL_CA_FILE is your SSL certificate to use for requests to GitLab Enterprise Edition. The certificate should be in PEM format. You can use the local file path to upload your certificate.

API

To connect your GitLab Enterprise Edition host to Cloud Build using the Cloud Build API, use the following JSON template. Unlike connecting your host using the Google Cloud console, you need to manually store your personal access tokens and webhook secret in Secret Manager before calling the API:

  {
      "username": "USERNAME",
      "secrets": {
        "apiAccessTokenVersion": "API_ACCESS_TOKEN_SECRET_VERSION",
        "readAccessTokenVersion": "READ_ACCESS_TOKEN_SECRET_VERSION",
        "webhookSecretVersion": "WEBHOOK_SECRET_SECRET_VERSION",
        "apiKeyVersion": "API_KEY_SECRET_VERSION"
      },
      "enterpriseConfig": {
        "hostUri": "HOST_URI",
        "sslCa": "SSL_CA",
        "serviceDirectoryConfig": {
          "service: "SERVICE_DIRECTORY_SERVICE"
        }
      }
  }

Replace the following:

USERNAME is your GitLab Enterprise Edition username.
API_ACCESS_TOKEN_SECRET_VERSION is the resource name of your api access token stored in Secret Manager. You may need to grant the Secret Manager role to your Cloud Build service account, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. To learn more, see Granting Secret Manager role to your service account.

Note: The expected format for the resource name for your secret stored in Secret Manager is projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/${VERSION_NUMBER}. You can specify latest as your version to use the latest version of your secret. This applies to each resource stored in Secret Manager.
READ_ACCESS_TOKEN_SECRET_VERSION is the resource name of your read access token stored in Secret Manager.
WEBHOOK_SECRET_SECRET_VERSION is the resource name of your of your webhook secret stored in Secret Manager.
API_KEY_SECRET_VERSION is the Google Cloud API key.
HOST_URI is the host URI of your GitLab Enterprise Edition instance.
[Optional] SSL_CA is your SSL certificate to use for requests to GitLab Enterprise Edition. The certificate should be in PEM format and be provided as a string.
[Optional] SERVICE_DIRECTORY_SERVICE is the name of the Service Directory Service that is used to communicate with your GitLab Enterprise Edition instance.

Enter the following curl command in your terminal:

  curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/gitLabConfigs?gitlabConfigId=GITLAB_ENTERPRISE_EDITION_CONFIG_NAME -d @config.json

Replace the following:

PROJECT_ID is your Google Cloud project ID.
REGION is the region where your GitLab Enterprise Edition configuration is located.

Note: You cannot connect your host when your region is set to global.
GITLAB_ENTERPRISE_EDITION_CONFIG_NAME is the name of your GitLab Enterprise Edition configuration.

What's next

Learn how to connect a GitLab Enterprise Edition repository.