Chapter 81: DevOps Projects Part 11: GitHub Actions GitLab CI Node Matrix Docker OIDC Terraform Runner Releases

81.7 Project 83: GitLab runner on EC2

By Ravindra Bagale Last updated: 28 October 2026

Friends, heavy jobs need your own runners. Today we launch an EC2 runner, install gitlab-runner, register with a tag, and run a job on that tag.

What you will build in this project

Launch a locked-down EC2 instance.
Install gitlab-runner.
Register with a project token and tag.
Route a job with tags.

1. Start from a real company story

At Persistent in Pune, shared SaaS runners queued for forty minutes during a release and missed a market window.

Rough cost: about ₹16 lakh in delayed launch ads.

Suresh put tagged EC2 runners next to the artifact store.

Today we register that runner.

Picture 1: GitLab → register token → EC2 gitlab-runner (tag docker) → job lands

Ravindra Bagale's Tip

Students open SSH from 0.0.0.0/0 on the runner. Restrict to bastion or SSM Session Manager. Keep that habit.

2. Start and prepare

Step 1: Why self-hosted

Why: Queues and data gravity. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: echo why. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 1: a1

Type this:

echo 'Self-hosted runners sit near your network and caches'

You will see:

Self-hosted runners sit near your network and caches

What it means: Why.

Example 2: a2

Type this:

mkdir -p /tmp/gl83 && echo 'Today: EC2, install, register, tags'

You will see:

Today: EC2, install, register, tags

What it means: Scope.

Example 3: a3

Type this:

echo 'Use SaaS runners for light open source; self-host for heavy private builds'

You will see:

Use SaaS runners for light open source; self-host for heavy private builds

What it means: When.

Step 2: EC2 tip

Why: Size and OS. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: notes. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 4: b1

Type this:

printf '%s\n' 'AMI: Ubuntu 22.04' 'Instance: t3.large for docker builds' 'Disk: 50 GB gp3' 'No public SSH; use SSM' > /tmp/gl83/EC2.txt && cat /tmp/gl83/EC2.txt

You will see:

No public SSH; use SSM

What it means: EC2.

Example 5: b2

Type this:

echo 'IAM instance profile for SSM and any deploy roles'

You will see:

IAM instance profile for SSM and any deploy roles

What it means: IAM.

Example 6: b3

Type this:

echo 'Put runners in a private subnet with NAT for pulls'

You will see:

Put runners in a private subnet with NAT for pulls

What it means: Network.

Step 3: Install gitlab-runner

Why: Package. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: install tip. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 7: c1

Type this:

echo 'curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash'

You will see:

curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash

What it means: Repo.

Example 8: c2

Type this:

echo 'sudo apt-get install -y gitlab-runner'

You will see:

sudo apt-get install -y gitlab-runner

What it means: Install.

Example 9: c3

Type this:

echo 'gitlab-runner --version'

You will see:

gitlab-runner --version

What it means: Version.

3. Build the main pieces

Step 4: Register

Why: Token and tag. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: register tip. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 10: d1

Type this:

printf '%s\n' 'sudo gitlab-runner register' '--url https://gitlab.example.com/' '--token RUNNER_AUTH_TOKEN' '--executor docker' '--docker-image docker:24' '--tag-list docker,ec2' '--description shop-ec2-1' > /tmp/gl83/REGISTER.txt && cat /tmp/gl83/REGISTER.txt

You will see:

--tag-list docker,ec2

What it means: Register.

Example 11: d2

Type this:

echo 'Get the runner auth token from GitLab Project -> Settings -> CI/CD -> Runners'

You will see:

Get the runner auth token from GitLab Project -> Settings -> CI/CD -> Runners

What it means: Token.

Example 12: d3

Type this:

echo 'executor shell is simpler; docker executor matches container jobs'

You will see:

executor shell is simpler; docker executor matches container jobs

What it means: Executor.

Step 5: Config.toml

Why: Verify. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: cat tip. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 13: e1

Type this:

echo 'sudo cat /etc/gitlab-runner/config.toml | head'

You will see:

sudo cat /etc/gitlab-runner/config.toml | head

What it means: Config.

Example 14: e2

Type this:

printf '%s\n' 'Check: name, url, token present, tags listed' > /tmp/gl83/CHECK.txt && cat /tmp/gl83/CHECK.txt

You will see:

Check: name, url, token present, tags listed

What it means: Check.

Example 15: e3

Type this:

echo 'sudo systemctl enable --now gitlab-runner'

You will see:

sudo systemctl enable --now gitlab-runner

What it means: Service.

Step 6: Job tags

Why: Route work. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: YAML. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 16: f1

Type this:

printf '%s\n' 'docker_build:' '  stage: build' '  tags: [ docker, ec2 ]' '  script:' '    - docker info' '    - docker build -t shop/api:$CI_COMMIT_SHORT_SHA .' > /tmp/gl83/JOB.txt && cat /tmp/gl83/JOB.txt

You will see:

tags: [ docker, ec2 ]

What it means: Job.

Example 17: f2

Type this:

echo 'Jobs without matching tags stay pending forever — check tags'

You will see:

Jobs without matching tags stay pending forever — check tags

What it means: Pending.

Example 18: f3

Type this:

printf '%s\n' 'Acceptance: job runs on shop-ec2-1 not SaaS' > /tmp/gl83/ACCEPT.txt && cat /tmp/gl83/ACCEPT.txt

You will see:

Acceptance: job runs on shop-ec2-1 not SaaS

What it means: Gate.

4. Automate and verify

Step 7: Security

Why: Runner trust. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: harden. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 19: g1

Type this:

printf '%s\n' 'One runner per trust zone (prod vs open source)' 'Disable privileged docker unless required' 'Rotate runner tokens on staff change' > /tmp/gl83/SEC.txt && cat /tmp/gl83/SEC.txt

You will see:

Disable privileged docker unless required

What it means: Sec.

Example 20: g2

Type this:

echo 'Never register a shared runner with prod cloud keys broadly'

You will see:

Never register a shared runner with prod cloud keys broadly

What it means: Keys.

Example 21: g3

Type this:

echo 'Protect the config.toml mode 0600'

You will see:

Protect the config.toml mode 0600

What it means: Mode.

Step 8: Pause resume

Why: Maintenance. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: cli. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 22: h1

Type this:

echo 'sudo gitlab-runner pause'

You will see:

sudo gitlab-runner pause

What it means: Pause.

Example 23: h2

Type this:

echo 'sudo gitlab-runner resume'

You will see:

sudo gitlab-runner resume

What it means: Resume.

Example 24: h3

Type this:

echo 'GitLab UI can also pause a runner during patching'

You will see:

GitLab UI can also pause a runner during patching

What it means: UI.

Step 9: Autoscaling tip

Why: Next step. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: fleet. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 25: i1

Type this:

echo 'docker-machine or fleeting plugins can autoscale EC2 runners'

You will see:

docker-machine or fleeting plugins can autoscale EC2 runners

What it means: Autoscale.

Example 26: i2

Type this:

echo 'Start with one steady runner; autoscale when queue time grows'

You will see:

Start with one steady runner; autoscale when queue time grows

What it means: When.

Example 27: i3

Type this:

echo 'Watch CloudWatch CPU and GitLab pending job metrics'

You will see:

Watch CloudWatch CPU and GitLab pending job metrics

What it means: Metrics.

5. Harden and accept

Step 10: Story Persistent

Why: Queue lag. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: story. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 28: j1

Type this:

printf '%s\n' 'At Persistent in Pune, SaaS runners queued 40 minutes and missed a market window.' 'Suresh put tagged EC2 runners next to the artifact store.' > /tmp/gl83/STORY.txt && wc -l /tmp/gl83/STORY.txt

You will see:

2 /tmp/gl83/STORY.txt

What it means: Story.

Example 29: j2

Type this:

echo 'Rough cost: about ₹16 lakh in delayed launch ads'

You will see:

Rough cost: about ₹16 lakh in delayed launch ads

What it means: Cost.

Example 30: j3

Type this:

echo 'Suresh: PASS'

You will see:

Suresh: PASS

What it means: Sign-off.

Step 11: Proof

Why: Notes. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: ls. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 31: k1

Type this:

ls /tmp/gl83

You will see:

ACCEPT.txt\nCHECK.txt\nEC2.txt\nJOB.txt\nREGISTER.txt\nSEC.txt\nSTORY.txt

What it means: Tree.

Example 32: k2

Type this:

grep tag-list /tmp/gl83/REGISTER.txt

You will see:

--tag-list docker,ec2

What it means: Tags.

Example 33: k3

Type this:

echo 'Next: Release automation with changelogs project 84'

You will see:

Next: Release automation with changelogs project 84

What it means: Bridge.

Step 12: Acceptance

Why: Tagged EC2 runner works. We do this before the next step so mistakes stay small and easy to undo. Read the output carefully; the numbers and names tell you if the machine is healthy.

What: final. Follow the numbered examples below. Type each command, read the exact output, and match the meaning line before you move on. That is how real teams learn a tool.

Example 34: z1

Type this:

echo 'gitlab-runner registered'

You will see:

gitlab-runner registered

What it means: Reg.

Example 35: z2

Type this:

echo 'Job with tags runs on EC2'

You will see:

Job with tags runs on EC2

What it means: Job.

Example 36: z3

Type this:

echo 'SSH not open to the world'

You will see:

SSH not open to the world

What it means: SSH.

Check yourself

Q1. Who fixed Persistent queue lag?

Suresh

Q2. Binary?

gitlab-runner

Q3. Route key?

Recap

Self-hosted for heavy jobs.
Tags route work.
Lock SSH down.
Pause for maintenance.
One runner one trust zone.