如何在GitLab作业中使用私有AWS ECR镜像？

以下是几个经过验证的解决办法，按优先级排序：

1. 直接在Runner配置中注入AWS凭证 #

放弃DOCKER_AUTH_CONFIG，在GitLab Runner的/etc/gitlab-runner/config.toml里给docker executor添加AWS环境变量，让Runner自动通过AWS凭证拉取ECR镜像：

[[runners]]
  name = "你的Runner名称"
  url = "你的GitLab实例地址"
  token = "你的Runner令牌"
  executor = "docker"
  [runners.docker]
    tls_verify = false
    image = "docker:latest"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache"]
    shm_size = 0
    # 添加AWS凭证相关环境变量
    environment = [
      "AWS_ACCESS_KEY_ID=AKIAXXX",
      "AWS_SECRET_ACCESS_KEY=xxx",
      "AWS_REGION=us-east-1"
    ]
    pull_policy = "always" # 确保每次拉取最新镜像，同时触发凭证验证

注意：给这个AWS账号分配最小权限，至少需要ecr:GetDownloadUrlForLayer、ecr:BatchGetImage、ecr:BatchCheckLayerAvailability这三个权限。

2. 让Runner使用本地Docker的Credential Helper配置 #

如果你的Runner服务器上已经配置好amazon-ecr-credential-helper且本地Docker能正常拉取镜像，让GitLab Runner复用这个配置：

1. 将本地的~/.docker/config.json（通常是root用户的）复制到GitLab Runner用户的家目录：

cp /root/.docker/config.json /home/gitlab-runner/.docker/
chown gitlab-runner:gitlab-runner /home/gitlab-runner/.docker/config.json

2. 修改/etc/gitlab-runner/config.toml，指定docker配置文件路径：

[[runners]]
  # 其他配置...
  [runners.docker]
    # 其他配置...
    docker_config = "/home/gitlab-runner/.docker/config.json"

3. 重启GitLab Runner服务：

gitlab-runner restart

3. 在CI作业中手动登录ECR #

如果上面两种方法都不行，直接在.gitlab-ci.yml的before_script里手动执行ECR登录命令，绕开DOCKER_AUTH_CONFIG的问题：

variables:
  AWS_REGION: "us-east-1"
  ECR_REPO_URI: "123456789012.dkr.ecr.us-east-1.amazonaws.com"

before_script:
  - aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $ECR_REPO_URI

job1:
  image: $ECR_REPO_URI/your-private-image:latest
  script:
    - echo "运行作业内容"

注意：需要在GitLab项目的设置>CI/CD>变量中添加AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY两个变量，并且确保Runner的基础镜像（比如上面用的docker:latest）已经安装了aws-cli，如果没有，需要在before_script里先安装。

排查要点 #

• 确认GitLab Runner的executor是docker或docker+machine，如果是shell executor，DOCKER_AUTH_CONFIG不会生效，直接用本地Docker的配置即可。
• 检查Runner版本，旧版本（比如13.x及以前）对ECR凭证的支持有问题，建议升级到最新稳定版。
• 验证DOCKER_AUTH_CONFIG的格式是否正确，ECR的token是临时的，手动生成的配置会在12小时后失效，这时候依赖Credential Helper自动刷新才是可靠的。

内容的提问来源于stack exchange，提问作者FiftiN