GitLab Runners & Container Registry

GitLab Runners

A Runner is the agent that executes CI/CD jobs. You can use GitLab's shared runners or install your own.

Installing a Runner

# Add GitLab Runner repository
curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" | sudo bash
 
# Install
sudo apt-get install gitlab-runner -y
 
# Verify
sudo gitlab-runner --version
sudo gitlab-runner status

Registering a Runner

In GitLab: Settings → CI/CD → Runners → New project runner
Copy the registration token
On your server:

sudo gitlab-runner register \
  --url https://gitlab.com \
  --token YOUR_REGISTRATION_TOKEN

You'll be prompted for:

Description: A name for your runner
Tags: Labels to target specific jobs (e.g., docker, deploy)
Executor: How jobs run (shell, docker, kubernetes)

Executor Types

Executor	Description	Best For
`shell`	Runs directly on the machine	Simple scripts, full access
`docker`	Runs inside Docker containers	Isolated, reproducible builds
`kubernetes`	Runs as K8s pods	Scalable, cloud-native

Runner Management

sudo gitlab-runner start
sudo gitlab-runner stop
sudo gitlab-runner restart
sudo gitlab-runner list    # Show registered runners
sudo gitlab-runner verify  # Check connectivity

Granting Permissions

# Add runner user to docker group
sudo usermod -aG docker gitlab-runner
 
# Grant sudo without password (for deploy scripts)
sudo visudo
# Add: gitlab-runner ALL=(ALL) NOPASSWD: ALL

GitLab Container Registry

Every GitLab project includes a private Docker registry for storing images.

Accessing the Registry

Navigate to: Deploy → Container Registry in your project.

The registry URL follows the pattern:

registry.gitlab.com/username/project-name

Pushing Images Manually

# Login to registry
docker login registry.gitlab.com
# Username: your GitLab username
# Password: Personal Access Token (with read/write registry scope)
 
# Build and tag
docker build -t registry.gitlab.com/username/project:latest .
 
# Push
docker push registry.gitlab.com/username/project:latest

Creating a Personal Access Token

Profile → Preferences → Access Tokens
Name: registry-access
Scopes: read_registry, write_registry
Click Create
Save the token (shown only once)

Pushing from CI/CD Pipeline

Use predefined variables for authentication:

build-image:
  stage: build
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA

Variable	Value
`$CI_REGISTRY`	`registry.gitlab.com`
`$CI_REGISTRY_USER`	Auto-generated username
`$CI_REGISTRY_PASSWORD`	Auto-generated token
`$CI_REGISTRY_IMAGE`	Full image path for your project

Complete Build & Push Pipeline

stages:
  - test
  - build
  - deploy
 
variables:
  IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
 
test:
  stage: test
  image: python:3.11
  script:
    - pip install -r requirements.txt
    - pytest
 
build:
  stage: build
  script:
    - docker build -t $IMAGE .
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker push $IMAGE
 
deploy:
  stage: deploy
  script:
    - docker pull $IMAGE
    - docker stop app || true
    - docker rm app || true
    - docker run -d --name app -p 80:80 $IMAGE
  environment:
    name: production
  when: manual
  only:
    - main

Runner Tags

Target specific runners using tags:

# In .gitlab-ci.yml
deploy:
  tags:
    - production
    - docker
  script:
    - ./deploy.sh

Only runners with matching tags will pick up this job.

Summary

Runners execute CI/CD jobs — install your own for full control
Register runners with gitlab-runner register and choose an executor
Shell executor runs directly; Docker executor provides isolation
GitLab Container Registry stores Docker images privately
Use $CI_REGISTRY_* variables for pipeline authentication
Tags route jobs to specific runners

Next Steps

Next, we'll deploy applications to Kubernetes environments using GitLab CI/CD pipelines.

Learning Objectives