GitLab has become a go-to DevOps platform because it offers powerful CI/CD automation straight out of the box. If you're new to GitLab pipelines, it's important to understand a few key building blocks: Runners, Variables & Secrets, and Artifacts.

In this blog, we’ll explain these terms simply with examples and use cases so that you can build secure, automated, and efficient pipelines. Let’s dive in! 👇

🛠️ Runner’s :

1. 🏃‍♂️ What is a GitLab Runner?

🔹 Definition:

A GitLab Runner is a lightweight agent that runs your CI/CD pipeline jobs. It reads your .gitlab-ci.yml file and executes steps like build, test, or deploy.

🔹 Meaning:

A GitLab Runner is a lightweight, highly scalable agent that runs CI/CD (Continuous Integration/Continuous Deployment) jobs from GitLab. It executes pipelines defined in .gitlab-ci.yml and sends the results back to GitLab.

• Key Functions of GitLab Runner

1. Executes Jobs – Runs tasks like building, testing, and deploying code.

2. Works with Pipelines – Processes stages defined in .gitlab-ci.yml.

3. Scalable – Can be installed on multiple machines (local, cloud, or containers) for parallel job execution.

4. Supports Multiple Executors – Can run jobs in:

   • Docker

   • Kubernetes

   • Shell (directly on the host machine)

   • Virtual Machines (VM)

   • SSH (remote servers)

• Types of GitLab Runners

• Instance Runners/Shared Runners – Managed by GitLab (available on GitLab.com for public projects or self-managed instances).

• Group Runners – Available to all projects within a GitLab group.

• Project-specific Runners – Dedicated to a single project.

• How It Works

1. GitLab detects a pipeline trigger (e.g., code push, merge request).

2. GitLab assigns jobs to available Runners.

3. The Runner fetches the code and executes the job based on .gitlab-ci.yml.

4. Results are reported back to GitLab (success/failure logs).

• Example Use Cases

• Automated Testing – Run unit/integration tests on every commit.

• Docker Image Building – Automatically build and push containers.

• Deployment – Deploy to staging/production when tests pass.

• Installation & Setup

• Goto project → Settings → CI/CD → Runners ( you can choose your priority )

---

🔹 GitLab Runner Types:

Project Runner, Group Runner and Shared Runner/Instance Runners

🧱 1. Project Runner

🔹 Definition:

A Project Runner is registered and used only for a specific GitLab project. It cannot be used by other projects unless manually assigned.

🎯 Use Case:

• When a project has custom requirements, like specific dependencies or a custom Docker image.

• Useful for isolation and security.

📍 Where to Find:

Project → Settings → CI/CD → Runners → Specific Runners

👪 2. Group Runner

🔹 Definition:

A Group Runner is assigned at the GitLab group level and is available to all projects within that group.

🎯 Use Case:

• When you manage multiple related projects (e.g., microservices) and want to reuse the same runner.

• Ensures consistency across pipelines in the group.

📍 Where to Find:

Group → Settings → CI/CD → Runners

🌍 3. Instance Runner (Shared Runner)

🔹 Definition:

An Instance Runner is registered at the GitLab instance level (admin level) and is available to every project on that GitLab server (self-managed or GitLab.com).

🎯 Use Case:

• Shared infrastructure across all teams.

• For organizations using self-hosted GitLab with centralized build servers.

📍 Where to Find (Self-managed GitLab only):

Admin Area → CI/CD → Runners

---

✅ Comparison Table

Now, How to Create a GitLab Project Runner ( Name: runner-1)

🪜 Step-by-Step Setup

🔹 Step 1: Install GitLab Runner (if not installed)

On the machine where you want to run the jobs (e.g., Ubuntu server):

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

🔹 Step 2: Go to Your Project Settings

• Navigate to your GitLab project

• Go to Settings → CI/CD

• Expand the Runners section

• Click on Create project runner

• give tag runner-1 & Create runner

You’ll find:

• Select Platform ( I'll go with Linux )

• click on How do I install GitLab Runner ? & Follow Steps ( in Your Ubuntu )

• Follow the Register Runner steps ( in Your Ubuntu )

🔹 Step 3: Verify the Runner in Ubuntu & GitLab UI

Ubuntu :

• gitlab-runner status- gitlab-runner: Service is running

• gitlab-runner start - Starts the runner service

• gitlab-runner stop - Stops the runner service

• gitlab-runner restart - Restarts the runner service

• gitlab-runner run

  • For debugging runner issues (you see logs directly in console)

  • During initial setup and verification

GitLab

• Go back to the Project → Settings → CI/CD → Runners

• You’ll now see runner-1 listed under "Available specific runners"

---

🔹 Step 5: Use the Runner in Your .gitlab-ci.yml

To ensure your pipeline uses runner-1, you can assign its tags:

build-job:
  stage: build
  script:
    - echo "Hello from runner-1 "
 tags:
    - runner-1

---

🎉 Done!

Your Project Runner runner-1 is now active and will run your pipeline jobs only for this project.

some time your pipeline is failed because runner remove old runners ( Instance runners ) you can try again 3,4 times otherwise :

Go to Ubuntu → home → gitla-runner → ls -a → edit file [ .bash_logout ] Add #️⃣ comment before all lines → wq + enter

Now your pipeline will run smoothly.

🆚 Self-Hosted vs SaaS (GitLab.com) Runners

CI/CD runners are the engines that execute your pipelines—but which type should you use? Let’s break it down.

🏠 1. Self-Hosted Runners

🔹 What Are They?

Runners that you install and manage on your own machine, server, or cloud VM. They can be assigned as project, group, or instance runners.

🛠️ Examples:

• A Linux VM with Docker

• AWS EC2, GCP Compute Engine

• On-premises physical server

✅ Pros:

• 🔒 Full control over environment

• 📦 Customize tools, images, and security

• 💸 No limit on usage (cost-effective for large teams)

• 🧰 Supports custom executors (Docker, Kubernetes, shell, etc.)

❌ Cons:

• ⚙️ You manage installation, scaling, and updates

• 🧯 Responsible for security and failure recovery

• 🧠 More DevOps knowledge required

The Project Runner runner-1 is also called as Self Hosted runner

---

☁️ 2. SaaS Runners ( GitLab-hosted )

🔹 What Are They?

Runners provided and maintained by GitLab.com. These are available out-of-the-box when using GitLab SaaS (https://gitlab.com).

🛠️ Examples:

• GitLab's own Docker-based runners (shared runners)

✅ Pros:

• 🚀 Quick setup (zero config)

• 🧑‍💻 No maintenance burden

• ☁️ Scales automatically

❌ Cons:

• ⛔️ Limited minutes in free plan (400 CI/CD mins/month)

• 🚫 No access to private networks or on-prem resources

• 🧩 Less control over environment and caching

---

🧪 Real-World Example:

---

📊 Summary Table

---

a single GitLab Runner can execute multiple pipelines, even across different projects. It picks up jobs based on tags and availability. This makes it efficient for handling parallel or queued CI/CD workloads.

---

⚙️ Choosing Between Self-Hosted and SaaS Runners: What's Right for You?

1. Self-Hosted Project Runner:

   If you've manually installed and registered a runner like runner-1 on your own server or machine, you're using a Self-Hosted Project Runner. This gives you full control over the environment, lets you install custom tools, and is ideal for secure, high-performance pipelines—especially when working within private networks or enterprise setups.

2. SaaS Shared Runner :

   On the other hand, if you're simply pushing code to GitLab and pipelines run automatically without you setting up anything, you're using a GitLab SaaS Shared Runner. These are fully managed by GitLab, require no setup or maintenance, and are great for quick starts, small projects, or open-source contributions—as long as you're okay with usage limits like the 400 CI/CD minutes per month on the free plan.

---

🔐 Variables & Secrets :

1. Variables

✅ What are Variables in GitLab?

Definition:
GitLab Variables are key-value pairs that you can use to pass dynamic data into your CI/CD pipelines.

They help you:

• Avoid hardcoding values

• Reuse configuration across jobs

• Safely inject secrets into your pipelines

🧰 Types of GitLab Variables

1️⃣ Inbuilt Variables (Predefined Variables)

Meaning:
Automatically created by GitLab during pipeline execution. You don’t need to define them.

• Automatically provided by GitLab.

• Start with CI_ or GITLAB_

• Cannot be modified by users.

📌 Use case:

script:
  - echo "Running on branch: $CI_COMMIT_BRANCH"

2️⃣ Custom Variables (User-Defined)

Meaning:
These are variables you create in GitLab (under Settings → CI/CD → Variables) to pass values like credentials or environment info.

• Defined by users in .gitlab-ci.yml or GitLab UI.

• Any name allowed (e.g., DEPLOY_ENV, API_KEY).

• Can be masked/protected for secrets.

• Example:

  yaml

    variables:
      DEPLOY_ENV: "production"  # Custom
      SECRET_KEY: $SECRET_KEY   # Defined in UI
  
    deploy:
      script:
        - echo "Env: $DEPLOY_ENV"  # Custom
  

✅ How to Add Your Own Variables (User-defined/Secrets)

Steps:

1. Go to your GitLab project

2. Settings → CI/CD → Variables

3. Click Add Variable

4. Fill in: For DockerHub Password

   • Key: e.g., DOCKERHUB_PASSWORD

   • Value: e.g., supersecret123

   • Enable ✅ Mask (optional) – hides it in logs

   • Enable ✅ Protect (optional) – only available in protected branches

     same process for DockerHub USER

---

✅ Using Variables in .gitlab-ci.yml

Using secrets securely:

script:
  - echo "$DOCKERHUB_PASSWORD" | docker login -u "$DOCKERHUB_USER" --password-stdin

🔐 Secrets in GitLab CI/CD

Best Practice:

• Never hardcode secrets in YAML.

• Use masked + protected for credentials.

---

• Key Difference

Built-in: Pipeline metadata (e.g., branch, job ID).
Custom: Configs (e.g., env vars).
Secret: Credentials (always protect!).

---

📁 Artifacts :

📦 What Are Artifacts in GitLab?

✅ Definition:

In GitLab CI/CD, an artifact is a file or directory created during a job that you want to save and share between pipeline stages or download after the pipeline finishes.

🎯 Key Use Cases:

1. Pass build outputs (e.g., binaries, logs) between jobs

2. Store test reports (JUnit, coverage) for visualization

3. Preserve debug files (logs, screenshots)

In simple words :

Artifacts are like final results or outputs of a job that you preserve for:

• Future stages (pass between jobs)

• Team inspection (download later)

• Debugging or analysis

🎯 Real-World Example:

Let’s say you have this pipeline:

1. A build job that creates a .jar file.

2. A test job that runs tests on that .jar.

3. You need to save and pass that .jar between jobs — use artifacts!

---

🔧 GitLab CI/CD Example Script:

stages:
  - build
  - test

build_job:  
  stage: build   
  script:  
    - echo "This is build job for Artifacts"
    - mkdir -p builds 
    - echo "This is Artifacts log" > builds/app.log
    - echo "More logs..." >> builds/app.log
  artifacts:  
    paths:  
      - builds           
    expire_in: 1 week

test_job:  
  stage: test  
  script:  
    - echo "This is test job using Artifacts"
    - cat builds/app.log
  artifacts:  
    paths:  
      - builds           
    expire_in: 1 hour

📘 Explanation:

• build_job creates a builds/ folder with a log file app.log.

• artifacts: tells GitLab to save the builds/ folder after the job.

• expire_in: 1 week keeps the artifact available for later jobs.

• test_job depends on build_job and uses the same artifact.

• test_job runs after build_job and automatically uses the saved artifact to read app.log.

---

🛠️ Common Use Cases:

✅ Bonus: Download Artifacts

You can download artifacts from:

1. GitLab UI → CI/CD → Pipelines → Job → Download artifacts

   

2. Or use GitLab API (for automation)

---

🧾 Summary:

• Artifacts = Output files saved from a job.

• Used to pass data between pipeline stages or for download/debug.

• Defined using artifacts: in .gitlab-ci.yml.

• Useful for compiled files, logs, test reports, configs, etc.

---

✅ Conclusion:

Understanding Runners, Variables, and Artifacts is essential to building powerful, secure, and maintainable GitLab pipelines.

• 🏃‍♂️ Runners are the backbone of GitLab CI/CD — they execute your pipeline jobs. Choosing between Self-Hosted and SaaS Shared Runners depends on your project’s complexity, performance needs, and control over infrastructure.

• 🔐 Variables and Secrets help you securely manage environment-specific values and credentials. Use custom and masked variables for flexibility, and never hardcode secrets in your YAML.

• 📦 Artifacts are your job outputs — whether logs, reports, or builds. Use them to pass data between stages, enable debugging, or generate deployable assets.

💡 Pro Tip: Combine these features to build secure, efficient, and automated DevOps workflows!

🧩 Stay tuned for Part 3 where we’ll build a real-world CI/CD project using GitLab!
🚀 From code to deployment — everything automated!