How OIDC can simplify authentication of GitLab CI/CD pipelines with Google Cloud

Hiroki Suezawa, Dhruv Jain ·
Jun 28, 2023 · 5 min read

In recent years, the integration of cloud services and GitLab through GitOps has become very common. Applications are now continuously tested and deployed through continuous integration and delivery (CI/CD); cloud environments are managed in code through Infrastructure as Code (IaC) using tools like Terraform; and GitLab CI is used as a core tool to perform these GitOps processes.

At the same time, software supply chain attacks have increased. To reduce the risk of an attack, the use of OpenID Connect (OIDC) auth is recommended, and GitLab 15.7 introduced ID tokens, a mechanism for secure OIDC integration.

However, OIDC integration can be complex for beginners and can be difficult to configure properly. Therefore, GitLab's Infrastructure Security Team has created a Terraform module for configuring Google Cloud and a CI template for GitLab CI so GitLab CI and Google Cloud can be securely integrated.

This tutorial explains how to use these OIDC modules.


The integration between Google Cloud and GitLab CI has often been done by adding a static key of the service account in Google Cloud to the environment variables of CI. However, this method has the following problems:

OIDC authentication can solve the above problems by providing the following benefits:

OIDC authentication with Google Cloud

The OIDC integration between Google Cloud and GitLab CI works as follows:

Simplified diagram

GitLab CI in action (simplified by the GitLab CI template in OIDC modules)

Google Cloud authenticates using an ID token issued on GitLab CI, so there is no need to issue a Google Cloud service account key.

How to use a Terraform module

The process of configuring a Terraform module to establish a connection between Google Cloud and GitLab using OIDC is fairly simple. This module takes care of the following steps:

  1. Create the Google Cloud Workload Identity Pool.
  2. Create a Workload Identity Provider.
  3. Grant permissions for service account impersonation.

Note: Your account must have at least the Workload Identity Pool Admin permission on the Google Cloud project.

# terraform
module "gl_oidc" {
 source = ""
 version = "3.0.0"
 google_project_id = GOOGLE_PROJECT_ID
 gitlab_project_id = GITLAB_PROJECT_ID
 oidc_service_account = {
   "sa" = {
     sa_email  = "SERVICE_ACCOUNT_EMAIL"
     attribute = "attribute.project_id/GITLAB_PROJECT_ID"

The above sample module can be used to configure OIDC. There are some additional parameters that can be used to configure this module further (a detailed list and description of those parameters can be found here).

By default, all branches of the project are authenticated to Google Cloud, but you can specify more granular conditions, such as the branch name of the commit that triggered the CI, or authenticating only with a specific tag.

Further settings can be made by changing the following attribute settings in accordance with the ID token claim:

  oidc_service_account = {
    "sa" = {
      sa_email  = "SERVICE_ACCOUNT_EMAIL"
      attribute = "attribute.project_id/GITLAB_PROJECT_ID"

Code files for this module are available here.

How to use the CI template

The CI template makes GitLab CI very easy for Google Cloud OIDC authentication. This CI template supports Application Default Credentials and can be used from IaC such as Terraform, CLI such as gcloud, and SDKs in Python and Go.

For example, if you want to use the CI template for Terraform, you can write:

# You should upgrade to the latest version. You can find the latest version at
  - remote: ''

    name: hashicorp/terraform:1.5.3
      - /usr/bin/env
      - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
  extends: .google-oidc:auth
    - terraform init
    - terraform plan

Required variables

A detailed list and description of those parameters can be found here.

As a note, you cannot use before_script in the job that uses this template because the way GitLab CI works will result in OIDC code being overwritten. CI template uses before_script to perform the initial configuration of OIDC.

Code samples for this module are available here.

Next steps

This article has introduced OIDC modules for OIDC integration and secure authentication between Google Cloud and GitLab CI. In short, we are doing the following steps:

  1. Setting up a service account
  2. Granting permissions to the service account
  3. Running the Terraform module
  4. Setting up CI pipeline

You can find the relevant sample for the above steps here.

Also, GitLab is currently developing a CI Catalog and CI Components. We plan to support them.

The GitLab Infrastructure Security Team will continue to improve the modules as we receive feedback, and we hope to consider and release components that maintain a high level of security and usability for both internal and external use.

Read more

“OIDC can sometimes be complex, but it's the safer and recommended way to authenticate your GitLab pipeline with Google Cloud. This tutorial walks you through the process step by step.” – Hiroki Suezawa, Dhruv Jain

Click to tweet

Edit this page View source