Install GitLab runner on EC2 with shell and docker executors

Install GitLab runner on EC2 with shell and docker executors

GitLab Runner is an open-source tool that runs CICD jobs in the pipeline. GitLab provides 400 min per month of runner time for free. It’s enough for individuals but not for the teams. GitLab allows you to set up your custom runner on any virtual machine. (separate from the server running GitLab if you have a self-hosted GitLab). Having our custom runner gives us benefits like better security and faster deployments.

In this blog, I will install a GitLab runner in an EC2. Please refer to this article if you don’t know how to spin up an EC2 instance; you can go for t3.micro if you want to benefit from the AWS free tier.

Please refer to the following instance configuration

  • Instance Size: t3.small (or t3.micro)
  • Operating System: Ubuntu 20.04 LTS
  • Attach Elastic IP
  • Keep the VPC security group and VPC default


Now follow the following steps:

SSH to the EC2 instance

Run the following command in your local machine to ssh to your EC2 instance

chmod 400 runner-key.pem
ssh -i runner-key.pem ubuntu@hostip

Install GitLab Runner

Now run these commands to install and start the GitLab runner service.

# Download the binary for your system
sudo curl -L --output /usr/local/bin/gitlab-runner

# Give it permission to execute
sudo chmod +x /usr/local/bin/gitlab-runner

# Create a GitLab Runner user
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash

# Install and run as a service
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

Before going forward, let’s discuss the concept of executors. The executors decide the environment where you want to run your job. For example,

If you want to run a shell command in your job, then the shell executor should be the choice, and if you want to run the jobs inside the docker container, you will have to use the docker executors. GitLab supports multiple types of runners; please refer to this to understand them.

In this blog, we will register the runners with shell and docker executors.

Register runner with Shell Executor

To register a runner, you will need a registration token from GitLab. For this, log in to your Gitlab account and click on any existing project or create a new one.

Inside the project got to Settings > CICD > Runners


You will see a token; keep this for the next step. Now go back to the EC2 shell and this command with the token you just copied.

sudo gitlab-runner register --url --registration-token $REGISTRATION_TOKEN

This command will ask for inputs and enter them according to this

  • Enter the GitLab instance URL: Keep it default unless you use a self-hosted GitLab Server.
  • Enter the registration token: Just press enter as we already entered the token in the command
  • Enter a description for the runner: Enter description as per your preference.
  • Enter tags for the runner: Enter tag for your runner: you can add multiple tags and keep them comma separated.
  • Enter optional maintenance node for the runner: Enter the maintenance message for a runner as per your preference. I'm keeping this blank.
  • Enter an executor: Put shell as we are registering a shell executor


As we are using Ubuntu 20:04, we might face issues while running the shell runner in the future due to this open issue.

We can resolve this issue by running this command.

sudo rm /home/gitlab-runner/.bash_logout

Now you are done registering the runner with shell executor, go to the GitLab dashboard and refresh the page, you will be able to see the runner with the tag.


Now let's install the Runner with Docker executor. but before that, we will have to install the Docker on the server.

Docker Installation

Run these two commands to install the latest stable version of docker

curl -fsSL -o
sudo sh

Run these two commands to provide permission of docker to the gitlab-runner user

sudo usermod -aG docker gitlab-runner
sudo service docker restart

Register runner with Docker executor

You can’t use the same token for registering two different runners; click on the Reset Registration token to reset the runner.

Now rerun the following command with the new token.

sudo gitlab-runner register --url --registration-token $REGISTRATION_TOKEN

Command will ask for similar information we have seen for shell runner. Just choose executor type as put a different tag, choose docker as executor, and alpine:latest as latest image.


Run this command to verify the runners:

sudo gitlab-runner verify

Now you have successfully installed the Gitlab runner with docker executor. Just go back to the Gitlab dashboard and refresh the page; you will be able to see two runners with different tags.


Testing the installation

As we finish the runner setup, it's time to test the installation. Add a simple .gitlab-ci.yml file in the repo with the following pipeline definition. Don't forget to change the runner name in the tags section if you use another name.

  - shell-runner-test
  - docker-runner-test

  stage: shell-runner-test
    - echo "This is Shell runner"
    - shell-runner

  stage: docker-runner-test
    - echo "This is Docker runner"
    - docker-runner

After saving this file, go to CI/CD > Pipelines. You will see a pipeline is triggered. You can click on individual jobs to see the output of the commands.


That’s all for this blog; We will use these runners for running the CI/CD jobs like scan, build and deploy in the upcoming blogs.

Did you find this article valuable?

Support Prateek Jain by becoming a sponsor. Any amount is appreciated!