Authenticating your GitLab CI runner to an AWS ECR registry using Amazon ECR Docker Credential Helper 🔑

GitLab CI allows you to run your CI/CD jobs in separate and isolated Docker containers. For maximum flexibility, you may need to run your jobs from a self-created Docker image tailored to your project’s specific needs. You can store this self-created and private Docker image in an AWS ECR registry. In this tutorial I will explain how to set up automatic authentication from your GitLab runner to your registry with Amazon ECR Docker Credential Helper.

GitLab CI job

Create a GitLab CI job which uses your Docker image saved in a private AWS ECR registry :

phpunit:
  stage: testing
  image: 
    name: 123456789123.dkr.ecr.us-east-1.amazonaws.com/php-gitlabrunner:latest
    entrypoint: [""]
  script:
    - php ./vendor/bin/phpunit --coverage-text --colors=never

Create and configure your runner to access AWS ECR registry

• Create an EC2 instance and install GitLab Runner
• Register your runner with Docker executor
• Install the AWS ECR Docker Credential Helper in your runner
• Create a /root/.docker/config.json file and add :

{
	"credsStore": "ecr-login"
}

• Create an IAM User with CLI access and attach arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly policy
• Paste CLI credentials to /root/.aws/credentials file on your GitLab runner :

[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR SECRET KEY

• Configure AWS Region in /root/.aws/config :

[default]
region = YOUR REGION

• Edit your /etc/gitlab-runner/config.toml to add in the [[runners]] section the following line environment = ["DOCKER_AUTH_CONFIG={ \"credsStore\": \"ecr-login\" }"] :

[[runners]]
  name = "gitlab-runner"
  url = "https://gitlab.com/"
  executor = "docker"
  [runners.custom_build_dir]
  [runners.cache]
    MaxUploadedArchiveSize = 0
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    image = "php:8-cli"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock", "/builds:/builds"]
    shm_size = 0
    environment = ["DOCKER_AUTH_CONFIG={ \"credsStore\": \"ecr-login\" }"]

Now your GitLab runner can automatically authenticate to your ECR registry ☺️