Setup Gitlab Runner with AWS ECR – Authenticate into Private Repository

Setup Gitlab Runner with AWS ECR

Getting Gitlab Runner to work with AWS ECR took me longer than I expected. The official docs on this specific scenario are thin, so I wrote down what I learned.

The Problem

There are two related problems you run into with ECR and GitLab Runner. Let me walk through both.

You want to pull a private image from ECR using the Docker executor. Your gitlab-ci.yml might look like this:

test-pull:
  image: ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/dev/build-container:latest
  script:
    - echo "Let's pull an image from a Private ECR Repository!"

Here, the Docker executor has to authenticate with AWS ECR before it can download the image from the repository.

The Solution

To authenticate the Docker executor against AWS ECR, you need two things:

1. Install the amazon-ecr-credential-helper on the Runner host.
2. Set the DOCKER_AUTH_CONFIG environment variable to { “credsStore”: “ecr-login” } in the Runner’s config.toml.

On Ubuntu, install the package like this:

sudo apt-get install -y amazon-ecr-credential-helper

Then configure the Runner. Every Runner has a config.toml file under /etc/gitlab-runner/. Add the environment variable there:

[[runners]]
  name = "Test"
  url = "https://gitlab.com/"
  token = "REDACTED"
  executor = "docker"
  environment = ["DOCKER_AUTH_CONFIG={ \"credsStore\": \"ecr-login\" }"]

That sets up the credential store for Docker. Just make sure the docker-credential-ecr-login binary is installed and in the PATH of the gitlab-runner user. AWS provides amazon-ecr-credential-helper, which handles authentication automatically based on your access keys or IAM role.

What does “automatic” mean here?

A normal docker login to ECR looks like this:

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin ACCOUNT_ID.dkr.ecr.region.amazonaws.com

I ran that command for a long time. The problem is that the ECR auth token expires after 12 hours. You have to re-run it twice a day.

The credential helper avoids that. Instead of the config.toml approach, you can also create a Docker config file on the Runner at /root/.docker/config.json (or ~gitlab-runner/.docker/config.json depending on your setup):

{
  "credsStore": "ecr-login"
}

That is all you need. Test your pipeline by pulling or pushing images to your private ECR repository.

Runner with Fargate

We covered how to deploy a Gitlab Runner on Fargate in a previous post. The same DOCKER_AUTH_CONFIG or config.json setup applies there too. Just make sure the credential helper binary is available inside your Fargate task.

Wrapping Up

Using AWS ECR with GitLab is straightforward once you know which approach to take. The hard part is finding the right setup path, because the documentation around this specific integration is scattered. I wrote this post so you can skip the digging and get it working.

If this helped you, consider sharing it.

Check also others articles related to Gitlab:

How to use the Gitlab CI Variables

Effective Cache Management with Maven Projects on Gitlab.

Pipeline to build Docker in Docker on Gitlab.

Execute Terraform on Gitlab CI.

How to use Gitlab CI: Deploy to elastic beanstalk