Setup Gitlab Runner with AWS ECR | aws ecr get login gitlab ci

Setup Gitlab Runner with AWS ECR – Authenticate into Private Repository

Setup Gitlab Runner with AWS ECR

There are some things you expect to work. However, unhappily trying to get Gitlab Runner with AWS ECR turned out to be quite a daunting job, and the small documentation in this area doesn’t help. 

The Problem

There are mainly two same but distinct problems when it comes to working with ECR. So let’s examine both of them individually:

Pulling a private image from ECR utilizing the docker Executor. E.g., if your gitlab-ci.yml looks like:

    - echo "Let's pull an image from a Private ECR Repository!"

In this situation, the Docker Executor requires “authenticate” to AWS ECR to download $PRIVATE_IMAGE from the ECR repository.

The Solution

So, for the first example, where you need to authenticate the Docker Executor to AWS ECR, you’ll need two things:

  1. Install the amazon-ecr-credential-helper on the Runner server.
  2. create and setup DOCKER_AUTH_CONFIG environment variable to { “credsStore”: “ecr-login” } in the config.toml of the runner.

For example, if you are using ubuntu on the Runner, you can install this package:

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

Now we can configure the Runner configuration file by adding the environment variable. All Runner server has one file called config.toml under /etc/gitlab-runner/


  name = "Test"
  url = ""
  token = "REDACTED"
  executor = "docker"
  environment = ["DOCKER_AUTH_CONFIG={ \"credsStore\": \"ecr-login\" 	}"]

Promptly, we’ve defined the Credential Store for Docker, but don’t forget to install the docker-credential-ecr-login in your Runner. So, AWS provides amazon-ecr-credential-helper, an excellent method of automatically authenticating with AWS ECR based on your Access Keys/IAM role. 

What does automatic mean here? 

So, the standard docker login is a basic auth command, where if you’ve to log in to ECR, you demand to do something similar:

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin

I used that command above for a long time. But, there is a downside here, where the token to authenticate to AWS ECR is only valid for 12 hours. So, it means that we need to run that command again every 12 hours.

However, there is a second alternative that doesn’t require changing the config.toml.

Suppose that you can have this file on your runner server /root/.docker/config.json, and the content of this:

  "credsStore": "ecr-login"

That’s it. Now, you can test your pipeline by pulling or pushing images to a private repository on AWS ECR.

Runner with Fargate

We already cover here on an article that presents a solution to deploy a Gitlab Runner on Fargate. In this scenario, we can configure the DOCKER_AUTH_CONFIG or config.json file for the root user, like described before.


Using the AWS ECR on Gitlab, it’s an easy process. However, the difficult part is to find the right solution or be aware of which approaches we have available. There is no documentation about this topic. So, I decided to write about it. Once you have the idea of how to authenticate, the process to do it, it’s easier.

I hope that you resolve your issue and enjoy your free time. 

Would you please help me share my post and website with your friends?

Take some minutes and follow me on social media.

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.

How to Autoscaling the Gitlab Runner.

Execute Terraform on Gitlab CI.

How to use Gitlab CI: Deploy to elastic beanstalk

Leave a Comment

Your email address will not be published. Required fields are marked *

Free PDF with a useful Mind Map that illustrates everything you should know about AWS VPC in a single view.