• Set up the Google Artifact Registry in a GitLab project
• View images stored in the Google Artifact Registry
• CI/CD
  • Predefined variables
  • Authenticate with the Google Artifact Registry
    • IAM policies
  • Examples
    • Use gcloud CLI to list images
    • Use crane to list images
    • Pull an image with Docker
    • Copy an image by using a CI/CD component
    • Copy an image by using Docker
    • Copy an image by using Crane

Google Artifact Management

This feature is in Beta.

You can use the Google Artifact Management integration to configure and connect a Google Artifact Registry repository to your GitLab project.

After you connect the Google Artifact Registry to your project, you can view, push, and pull Docker and OCI images in a Google Artifact Registry repository.

Set up the Google Artifact Registry in a GitLab project

Prerequisites:

• You must have at least the Maintainer role for the GitLab project.
• You must have the permissions needed to manage access to the Google Cloud project with the Artifact Registry repository.
• A workload identity federation (WLIF) pool and provider must be configured to authenticate to Google Cloud.
• A Google Artifact Registry repository with the following configuration:
  • Docker format.
  • Standard mode. Other repository formats and modes are not supported.

To connect a Google Artifact Registry repository to a GitLab project:

1. In GitLab, on the left sidebar, select Search or go to and find your project.
2. Select Settings > Integrations.
3. Select Google Artifact Management.
4. Under Enable integration, select the Active checkbox.
5. Complete the fields:
   • Google Cloud project ID: The Google Cloud project ID where the Artifact Registry repository is located.
   • Repository name: The name of the Artifact Registry repository.
   • Repository location: The Google Cloud location of the Artifact Registry repository.
6. Follow the onscreen instructions to set up the Google Cloud Identity and Access Management (IAM) policies. For more information about the types of policies, see IAM policies.
7. Select Save changes.

You should now see a Google Artifact Registry entry in the sidebar under Deploy.

View images stored in the Google Artifact Registry

Prerequisites:

• The Google Artifact Registry must be configured in the project.

To view the list of images in the connected Artifact Registry repository in the GitLab UI:

1. On the left sidebar, select Search or go to and find your project.
2. Select Deploy > Google Artifact Registry.
3. To view the image details, select an image.
4. To view the image in the Google Cloud console, select Open in Google Cloud. You must have the required permissions to view that Artifact Registry repository.

CI/CD

Predefined variables

After the Artifact Registry integration is activated, the following predefined environment variables are available in CI/CD. You can use these environment variables to interact with the Artifact Registry, like pulling or pushing an image to the connected repository.

Authenticate with the Google Artifact Registry

You can configure a pipeline to authenticate with the Google Artifact Registry during pipeline execution. GitLab uses the configured workload identity pool IAM policies and populates the GOOGLE_APPLICATION_CREDENTIALS and CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE environment credentials. These environment credentials are automatically detected by client tools, like gcloud CLI and crane.

To authenticate with the Google Artifact Registry, in the project’s .gitlab-ci.yml file, use the identity keyword set to google_cloud.

IAM policies

Your Google Cloud project must have specific IAM policies to use the Google Artifact Management integration. When you set up this integration, on-screen instructions provide the steps to create the following IAM policies in your Google Cloud project:

• Grant Artifact Registry Reader role to GitLab project members with Guest role or above.
• Grant Artifact Registry Writer role to GitLab project members with Developer role or above.

To create these IAM policies manually, use the following gcloud commands. Replace these values:

• <your_google_cloud_project_id> with the ID of the Google Cloud project where the Artifact Registry repository is located.
• <your_workload_identity_pool_id> with the ID of the workload identity pool. This is the same value used for the Google Cloud IAM integration.
• <your_google_cloud_project_number> with the number of the Google Cloud project where the workload identity pool is located. This is the same value used for the Google Cloud IAM integration.

gcloud projects add-iam-policy-binding '<your_google_cloud_project_id>' \
  --member='principalSet://iam.googleapis.com/projects/<your_google_cloud_project_number>/locations/global/workloadIdentityPools/<your_workload_identity_pool_id>/attribute.guest_access/true' \
  --role='roles/artifactregistry.reader'

gcloud projects add-iam-policy-binding '<your_google_cloud_project_id>' \
  --member='principalSet://iam.googleapis.com/projects/<your_google_cloud_project_number>/locations/global/workloadIdentityPools/<your_workload_identity_pool_id>/attribute.developer_access/true' \
  --role='roles/artifactregistry.writer'

For a list of available claims, see OIDC custom claims.

Examples

Use gcloud CLI to list images

list-images:
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:466.0.0-alpine
  identity: google_cloud
  script:
    - gcloud artifacts docker images list $GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION-docker.pkg.dev/$GOOGLE_ARTIFACT_REGISTRY_PROJECT_ID/$GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_NAME/app

Use crane to list images

list-images:
  image: 
    name: gcr.io/go-containerregistry/crane:debug
    entrypoint: [""]
  identity: google_cloud
  before_script:
    # Temporary workaround for https://github.com/google/go-containerregistry/issues/1886
    - wget -q "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v2.1.22/docker-credential-gcr_linux_amd64-2.1.22.tar.gz" -O - | tar xz -C /tmp && chmod +x /tmp/docker-credential-gcr && mv /tmp/docker-credential-gcr /usr/bin/
    - docker-credential-gcr configure-docker --registries=$GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION-docker.pkg.dev
  script:
    - crane ls $GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION-docker.pkg.dev/$GOOGLE_ARTIFACT_REGISTRY_PROJECT_ID/$GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_NAME/app

Pull an image with Docker

The following example shows how to set up authentication for Docker with the standalone Docker credential helper provided by Google.

pull-image:
  image: docker:24.0.5
  identity: google_cloud
  services:
    - docker:24.0.5-dind
  variables:
    # The following two variables ensure that the DinD service starts in TLS
    # mode and that the Docker CLI is properly configured to communicate with
    # the API. More details about the importance of this can be found at
    # https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#use-the-docker-executor-with-docker-in-docker
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - wget -q "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v2.1.22/docker-credential-gcr_linux_amd64-2.1.22.tar.gz" -O - | tar xz -C /tmp && chmod +x /tmp/docker-credential-gcr && mv /tmp/docker-credential-gcr /usr/bin/
    - docker-credential-gcr configure-docker --registries=$GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION-docker.pkg.dev
  script:
    - docker pull $GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION-docker.pkg.dev/$GOOGLE_ARTIFACT_REGISTRY_PROJECT_ID/$GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_NAME/app:v0.1.0

Copy an image by using a CI/CD component

Google provides the upload-artifact-registry CI/CD component, which you can use to copy an image from the GitLab container registry to Artifact Registry.

To use the upload-artifact-registry component, add the following to your .gitlab-ci.yml:

include:
  - component: gitlab.com/google-gitlab-components/artifact-registry/upload-artifact-registry@main
    inputs:
      stage: deploy
      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

For details, see the component documentation.

Using the upload-artifact-registry component simplifies copying images to Artifact Registry and is the intended method for this integration. If you want to use Docker or Crane, see the following examples.

Copy an image by using Docker

In the following example, the gcloud CLI is used to set up the Docker authentication, as an alternative to the standalone Docker credential helper.

copy-image:
  image: gcr.io/google.com/cloudsdktool/google-cloud-cli:466.0.0-alpine
  identity: google_cloud
  services:
    - docker:24.0.5-dind
  variables:
    SOURCE_IMAGE: $CI_REGISTRY_IMAGE:v0.1.0
    TARGET_IMAGE: $GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION-docker.pkg.dev/$GOOGLE_ARTIFACT_REGISTRY_PROJECT_ID/$GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_NAME/app:v0.1.0
    DOCKER_HOST: tcp://docker:2375
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - gcloud auth configure-docker $GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION-docker.pkg.dev
  script:
    - docker pull $SOURCE_IMAGE
    - docker tag $SOURCE_IMAGE $TARGET_IMAGE
    - docker push $TARGET_IMAGE

Copy an image by using Crane

copy-image:
  image: 
    name: gcr.io/go-containerregistry/crane:debug
    entrypoint: [""]
  identity: google_cloud
  variables:
    SOURCE_IMAGE: $CI_REGISTRY_IMAGE:v0.1.0
    TARGET_IMAGE: $GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION-docker.pkg.dev/$GOOGLE_ARTIFACT_REGISTRY_PROJECT_ID/$GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_NAME/app:v0.1.0
  before_script:
    # Temporary workaround for https://github.com/google/go-containerregistry/issues/1886
    - wget -q "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v2.1.22/docker-credential-gcr_linux_amd64-2.1.22.tar.gz" -O - | tar xz -C /tmp && chmod +x /tmp/docker-credential-gcr && mv /tmp/docker-credential-gcr /usr/bin/
    - docker-credential-gcr configure-docker --registries=$GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION-docker.pkg.dev
  script:
    - crane auth login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - crane copy $SOURCE_IMAGE $TARGET_IMAGE