Tutorial: Set up the Google Cloud integration

This tutorial shows you how to integrate Google Cloud with GitLab, so that you can deploy directly to Google Cloud.

To set up the Google Cloud integration:

1. Secure your usage with Google Cloud Identity and Access Management (IAM)
2. Connect to a Google Artifact Registry repository
3. Set up GitLab Runner to execute your CI/CD jobs on Google Cloud
4. Deploy to Google Cloud with CI/CD components

Before you begin

To set up the integration, you must:

• Have a GitLab project where you have at least the Maintainer role.
• Have the Owner IAM role on the Google Cloud projects that you want to use.
• Have billing enabled for your Google Cloud project.
• Have a Google Artifact Registry repository with Docker format and Standard mode.
• Install the Google Cloud CLI and Terraform.

Secure your usage with Google Cloud Identity and Access Management (IAM)

To secure your usage of Google Cloud, you must set up the Google Cloud IAM integration. After this step, your GitLab group or project is connected to Google Cloud. You can handle permissions for Google Cloud resources without the need for service accounts keys and the associated risks using workload identity federation.

1. On the left sidebar, select Search or go to and find your group or project. If you configure this on a group, settings apply to all projects within by default.
2. Select Settings > Integrations.
3. Select Google Cloud IAM.
4. Select Guided setup and follow the instructions.

Connect to a Google Artifact Registry repository

Now that the Google IAM integration is set up, you can connect to a Google Artifact Registry repository. After this step, you can view your Google Cloud artifacts in GitLab.

1. In your GitLab project, on the left sidebar, select Settings > Integrations.
2. Select Google Artifact Registry.
3. Under Enable integration, select the Active checkbox.
4. Complete the fields:
   • Google Cloud project ID: The ID of the Google Cloud project where your Artifact Registry repository is located.
   • Repository name: The name of your Artifact Registry repository.
   • Repository location: The location of your Artifact Registry repository.
5. In Configure Google Cloud IAM policies, follow the onscreen instructions to set up the IAM policies in Google Cloud. These policies are required to use the Artifact Registry repository in your GitLab project.
6. Select Save changes.
7. To view your Google Cloud artifacts, on the left sidebar, select Deploy > Google Artifact Registry.

In a later step, you will push your container images to Google Artifact Registry.

Set up GitLab Runner to execute your CI/CD jobs on Google Cloud

You can set up GitLab Runner to run CI/CD jobs on Google Cloud. After this step, your GitLab project has an autoscaling fleet of runners, with a runner manager that creates temporary runners to execute multiple jobs simultaneously.

1. In your GitLab project, on the left sidebar, select Settings > CI/CD.
2. Expand the Runners section.
3. Select New project runner.
4. Complete the fields.
   • In the Platform section, select Google Cloud.
   • In the Tags section, in the Tags field, enter the job tags to specify jobs the runner can run. If there are no job tags for this runner, select Run untagged.
   • Optional. In the Runner description field, add a description for the runner that displays in GitLab.
   • Optional. In the Configuration section, add additional configurations.
5. Select Create runner.
6. Complete the fields in the Step 1: Specify environment section to specify the environment in Google Cloud where runners execute CI/CD jobs.
7. Under Step 2: Set up GitLab Runner, select Setup instructions.
8. Follow the instructions in the modal. You only need to do Step 1 once for the Google Cloud project, so that it's ready to provision the runners.

After you've followed the instructions, it might take one minute for your runner to be online and ready to run jobs.

Deploy to Google Cloud with CI/CD components

A best practice for development is to reuse syntax, like CI/CD components to keep consistency across your pipelines.

You can use the library of components from GitLab and Google to make your GitLab project interact with Google Cloud resources. See the CI/CD components from Google.

Copy container images to Google Artifact Registry

Before you begin, you must have a working CI/CD configuration that builds and pushes container images to your GitLab container registry.

To copy container images from your GitLab container registry to your Google Artifact Registry, include the CI/CD component from Google in your pipeline. After this step, whenever a new container image is pushed to your GitLab container registry, it is also pushed to your Google Artifact Registry.

1. In your GitLab project, on the left sidebar, select Build > Pipeline editor.

2. In the existing configuration, add the component as follows.

   • Replace <your_stage> with the stage where this job runs. It must be after the image is built and pushed to the GitLab container registry.

   include:
     - component: gitlab.com/google-gitlab-components/artifact-registry/upload-artifact-registry@main
       inputs:
         stage: <your_stage>
         source: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
         target: $GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION-docker.pkg.dev/$GOOGLE_ARTIFACT_REGISTRY_PROJECT_ID/$GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_NAME/$CI_PROJECT_NAME:$CI_COMMIT_SHORT_SHA

3. Add a descriptive commit message. Target branch must be your default branch.

4. Select Commit changes.

5. Go to Build > Pipelines and make sure a new pipeline runs.

6. After the pipeline finishes successfully, to view the container image that was copied to Google Artifact Registry, on the left sidebar, select Deploy > Google Artifact Registry.

Create a Google Cloud Deploy release

To integrate your pipeline with Google Cloud Deploy, include the CI/CD component from Google in your pipeline. After this step, your pipeline creates a Google Cloud Deploy release with your application.

1. In your GitLab project, on the left sidebar, select Build > Pipeline editor.
2. In the existing configuration, add the Google Cloud Deploy component.
3. Edit the component inputs.
4. Add a descriptive commit message. Target branch must be your default branch.
5. Select Commit changes.
6. Go to Build > Pipelines and make sure a new pipeline passes.
7. After the pipeline finishes successfully, to view the release, see the Google Cloud documentation.

And that's it! You've now integrated Google Cloud with GitLab, and your GitLab project seamlessly deploys to Google Cloud.

Related topics

• Google Cloud IAM integration
• Google Artifact Management integration
• Provisioning runners in Google Cloud