Connect to a GitLab host

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

Before you begin

Enable the Cloud Build and Secret Manager APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role ( roles/serviceusage.serviceUsageAdmin ), which contains the serviceusage.services.enable permission. Learn how to grant roles .

Enable the APIs

Connect to a GitLab host

Before creating a host connection for your GitLab instance, you must create personal access tokens in GitLab by completing the following steps:

Log into your GitLab instance.
On the GitLab page for your instance, click your avatar in the upper-right corner.
Click Edit profile.
On the left sidebar, select Access tokens.

You see the Personal Access Tokens page.
Create an access token with the api scope to use for connecting and disconnecting repositories.
Create an access token with the read_api scope to ensure Cloud Build repositories can access source code in repositories.

Note: In addition to personal access tokens , you can also use project access tokens . If your GitLab version is 14.2 or higher, you can also use group access tokens . If you use project or group access tokens, select the Maintainer role to ensure a successful connection.

Console

To connect your GitLab host to Cloud Build:

Open the Repositoriespage in the Google Cloud console.

Open the Repositories page

You see the Repositoriespage.
At the top of the page, select the 2nd gentab.
In the project selector in the top bar, select your Google Cloud project.
Click Create host connectionto connect a new host to Cloud Build.
On the left panel, select GitLabas your source provider.
In the Configure Connectionsection, enter the following information:
1. Region: Select a region for your connection.
  
  Note: You must specify a region. Your connection cannot exist globally.
2. Name: Enter a name for your connection.
In the Host detailssection, select or enter the following information:
1. GitLab provider: Select GitLab.comas your provider.
In the Personal access tokenssection, enter the following information:
1. API access token: Enter the token with the api scope access. This token is used for connecting and disconnecting repositories.
2. Read API access token: Enter the token with the read_api scope access. Cloud Build triggers use this token to access source code in repositories.
Click Connect.

After clicking the Connectbutton, your personal access tokens 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 .

You have now successfully created a GitLab connection.

gcloud

Prior to connecting your GitLab host to Cloud Build, complete the following steps to store your credentials:

Store your token in Secret Manager .

Create a webhook secret in Secret Manager by running the following command:

 cat /proc/sys/kernel/random/uuid | tr -d '\n' | gcloud secrets create my-gle-webhook-secret --data-file=-

If you store your secrets in a different Google Cloud project than the one you plan to use to create a host connection, enter the following command to grant your project access to the Cloud Build service agent:

 PN=$(gcloud  
projects  
describe  
 PROJECT_ID 
  
--format="value(projectNumber)")
CLOUD_BUILD_SERVICE_AGENT="service- ${ 
 PN 
 } 
@gcp-sa-cloudbuild.iam.gserviceaccount.com"
gcloud  
projects  
add-iam-policy-binding  
 PROJECT_ID 
  
\  
--member="serviceAccount: ${ 
 CLOUD_BUILD_SERVICE_AGENT 
 } 
"  
\  
--role="roles/secretmanager.admin"

Where:

PROJECT_ID is your Google Cloud project ID.

You can now proceed to connect your GitLab host to Cloud Build.

Complete the following steps:

To connect your GitLab host to Cloud Build:

Enter the following command to create a GitLab connection:

  gcloud 
  
 builds 
  
 connections 
  
 create 
  
 gitlab 
  
  CONNECTION_NAME 
 
  
 \ 
  
 -- 
 host 
 - 
 uri 
 = 
  HOST_URI 
 
  
 \ 
  
 -- 
 project 
 = 
  PROJECT_ID 
 
  
 \ 
  
 -- 
 region 
 = 
  REGION 
 
  
 \ 
  
 -- 
 authorizer 
 - 
 token 
 - 
 secret 
 - 
 version 
 = 
 projects 
 / 
  PROJECT_ID 
 
 / 
 secrets 
 / 
  API_TOKEN 
 
 / 
 versions 
 / 
  SECRET_VERSION 
 
  
 \ 
  
 -- 
 read 
 - 
 authorizer 
 - 
 token 
 - 
 secret 
 - 
 version 
 = 
 projects 
 / 
  PROJECT_ID 
 
 / 
 secrets 
 / 
  READ_TOKEN 
 
 / 
 versions 
 / 
  SECRET_VERSION 
 
  
 \ 
  
 -- 
 webhook 
 - 
 secret 
 - 
 secret 
 - 
 version 
 = 
 projects 
 / 
  PROJECT_ID 
 
 / 
 secrets 
 / 
  WEBHOOK_SECRET 
 
 / 
 versions 
 / 
  SECRET_VERSION

Where:

CONNECTION_NAME is a name for your GitLab host connection in Cloud Build.
HOST_URI is the URI of your GitLab instance. For example, https://my-gle-server.net .
PROJECT_ID is your Google Cloud project ID.
REGION is the region for your connection.
API_TOKEN is the name of your token with api scope.
READ_TOKEN is the name of your token with read_api scope.
SECRET_VERSION is the version of your secret.
WEBHOOK_SECRET is your webhook secret.

You have now successfully created a GitLab connection.

Rotate old or expired GitLab access tokens

If your GitLab access token expires, then your Cloud Build host connection is disconnected from its GitLab repository. As a result, you will see errors in the following circumstances:

When you try to link a GitLab repository Cloud Build connection, a Failed to fetch repositories to link. Check that Cloud Build is still authorized to access data from the selected connection message appears.
On the Triggerspage, when you click Run, the Run triggerpage opens and shows a Failed to list branches. You can still enter one manually message.

To rotate an old or expired token for your connection, do the following:

Find the secrets associated with your host connection:
1. Run the following command:
```
 gcloud  
builds  
connections  
describe  
 CONNECTION_PATH 
  
--region = 
 REGION 
 
```
  Where:
  - CONNECTION_PATH is the path of your GitLab host connection in Cloud Build, in the format projects/ PROJECT_ID /locations/ REGION /connections/ CONNECTION_NAME .
  - REGION is the region for your connection.
2. In the output of the command, look for the values of your user token fields. readAuthorizerCredential.userTokenSecretVersion shows the Secret Manager name of the read_api token, and authorizerCredential.userTokenSecretVersion shows the Secret Manager name of the api token. These names are stored as secrets in Secret Manager.
Rotate each access token in GitLab:
1. Go to the GitLab repository connected to your Cloud Build host connection.
2. Follow the instructions in the GitLab documentation to rotate an access token . When you rotate a token, GitLab creates a new token with new credentials and invalidates the previous version of that token. Your rotated token has the same permissions and scope as the original token.
3. Copy the ID of your rotated token.
Create a new secret version for each token:
1. Open the Secret Manager page in the Google Cloud console:
  
  Open the Secret Manager page
2. For each token that you rotated, find the secret name that you identified in Step 1 and click Actions , and then click Add new version.
  
  Note: If you can't find your secret in the Secretswindow, select the Regional Secretstab and look for your secret in the Regional Secretswindow.
3. In the Add new versionwindow, enter the ID of your rotated token and then click Add new version.

For more information, see Access token expiration in the GitLab documentation.

What's next

Learn how to connect a GitLab repository .
Learn how to build and deploy your workloads to Google Cloud using Google-managed CI/CD components in your GitLab pipeline. See GitLab on Google Cloud .

Connect to a GitLab host Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Connect to a GitLab host

Console

gcloud

Rotate old or expired GitLab access tokens

What's next

Connect to a GitLab host