Help us learn about your current experience with the documentation. Take the survey.

Google 工件管理

层级：免费版、高级版、旗舰版
提供：GitLab.com

您可以使用 Google Artifact Management 集成，将 Google Artifact Registry 仓库配置并连接到您的 GitLab 项目。

连接 Google Artifact Registry 到项目后，您可以在 Google Artifact Registry 仓库中查看、推送和拉取 Docker 和 OCI 镜像。

在 GitLab 项目中设置 Google Artifact Registry

前置条件：

您必须至少拥有 GitLab 项目的 Maintainer（维护者）角色。
您必须拥有所需的权限来管理包含 Artifact Registry 仓库的 Google Cloud 项目的访问权限。
必须配置 workload identity federation (WLIF) 池和提供程序，以向 Google Cloud 进行身份验证。
一个具有以下配置的 Google Artifact Registry 仓库：
- Docker 格式。
- Standard 模式。不支持其他仓库格式和模式。

将 Google Artifact Registry 仓库连接到 GitLab 项目：

在 GitLab 中，在左侧边栏选择 Search or go to 并找到您的项目。
选择 Settings > Integrations。
选择 Google Artifact Management。
在 Enable integration 下，选择 Active 复选框。
完成以下字段：
- Google Cloud project ID：Artifact Registry 仓库所在的 Google Cloud project ID。
- Repository name：Artifact Registry 仓库的名称。
- Repository location：Artifact Registry 仓库的 Google Cloud location。
按照屏幕上的说明设置 Google Cloud Identity and Access Management (IAM) 策略。有关策略类型的更多信息，请参阅 IAM policies。
选择 Save changes。

您现在应该在 Deploy 下的侧边栏中看到 Google Artifact Registry 条目。

查看 Google Artifact Registry 中存储的镜像

前置条件：

项目中必须配置 Google Artifact Registry。

在 GitLab UI 中查看连接的 Artifact Registry 仓库中的镜像列表：

在左侧边栏选择 Search or go to 并找到您的项目。
选择 Deploy > Google Artifact Registry。
要查看镜像详细信息，请选择一个镜像。
要在 Google Cloud 控制台中查看镜像，请选择 Open in Google Cloud。您必须拥有所需的权限才能查看该 Artifact Registry 仓库。

CI/CD

预定义变量

Artifact Registry 集成激活后，以下预定义的环境变量在 CI/CD 中可用。您可以使用这些环境变量与 Artifact Registry 交互，例如将镜像拉取或推送到连接的仓库。

Variable	GitLab	Runner	Description
`GOOGLE_ARTIFACT_REGISTRY_PROJECT_ID`	16.10	16.10	Artifact Registry 仓库所在的 Google Cloud 项目 ID。
`GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_NAME`	16.10	16.10	连接的 Artifact Registry 仓库的名称。
`GOOGLE_ARTIFACT_REGISTRY_REPOSITORY_LOCATION`	16.10	16.10	连接的 Artifact Registry 仓库的 Google Cloud 位置。

向 Google Artifact Registry 进行身份验证

您可以配置管道，在管道执行期间向 Google Artifact Registry 进行身份验证。GitLab 使用配置的 workload identity pool IAM 策略，并填充 GOOGLE_APPLICATION_CREDENTIALS 和 CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE 环境凭据。这些环境凭据会被客户端工具（如 gcloud CLI 和 crane）自动检测。

要向 Google Artifact Registry 进行身份验证，请在项目的 .gitlab-ci.yml 文件中使用设置为 google_cloud 的 identity 关键字。

IAM 策略

您的 Google Cloud 项目必须具有特定的 IAM 策略才能使用 Google Artifact Management 集成。当您设置此集成时，屏幕上的说明会提供在您的 Google Cloud 项目中创建以下 IAM 策略的步骤：

向拥有 Guest 角色或更高角色的 GitLab 项目成员授予 Artifact Registry Reader 角色。
向拥有 Developer 角色或更高角色的 GitLab 项目成员授予 Artifact Registry Writer 角色。

要手动创建这些 IAM 策略，请使用以下 gcloud 命令。替换这些值：

<your_google_cloud_project_id> 替换为 Artifact Registry 仓库所在的 Google Cloud 项目的 ID。
<your_workload_identity_pool_id> 替换为 workload identity pool 的 ID。这是用于 Google Cloud IAM 集成的相同值。
<your_google_cloud_project_number> 替换为 workload identity pool 所在的 Google Cloud 项目的 number。这是用于 Google Cloud IAM 集成的相同值。

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'

有关可用声明的列表，请参阅 OIDC 自定义声明。

示例

使用 gcloud CLI 列出镜像

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

使用 crane 列出镜像

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

使用 Docker 拉取镜像

以下示例展示了如何使用 Google 提供的 standalone Docker credential helper 为 Docker 设置身份验证。

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

使用 CI/CD 组件复制镜像

Google 提供了 upload-artifact-registry CI/CD 组件，您可以使用它将镜像从 GitLab 容器仓库复制到 Artifact Registry。

要使用 upload-artifact-registry 组件，请将以下内容添加到您的 .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

有关详细信息，请参阅 the component documentation。

使用 upload-artifact-registry 组件简化了将镜像复制到 Artifact Registry 的过程，并且是此集成的预期方法。如果您想使用 Docker 或 Crane，请参阅以下示例。

使用 Docker 复制镜像

在以下示例中，使用 gcloud CLI 设置 Docker 身份验证，作为 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

使用 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