GitLab CI/CD: Creating Your First Pipeline & Understanding Jobs and Stages

Welcome to Chapter 2 of Mastering GitLab CI/CD Pipeline Fundamentals: From Basics to Advanced. This chapter provides a hands-on, end-to-end tutorial on creating your very first GitLab CI/CD pipeline from scratch. You will learn how GitLab projects combine code repositories with CI/CD capabilities, how to write pipeline configurations using YAML, and how to structure execution using stages and jobs.

1. Prerequisites and Initial GitLab Project Setup

Before writing any CI/CD automation, you need a properly initialized workspace inside GitLab. Unlike traditional version control systems where repositories only store source code, GitLab treats a repository as a Project—a unified workspace that tightly couples your source code repository with integrated pipeline automation, issue tracking, and deployment tools.

Initial Setup Workflow

1. Account Registration: Create and verify your GitLab account. If your account encounters verification checks or blocks during creation, complete the required verification steps immediately to unlock pipeline execution permissions.
2. Project Creation: Create a new project by defining a group name and a project name. This groups your repositories logically.
3. Workspace Customization: Navigate into your newly created project and adjust your user interface preferences (such as switching to a dark theme for better visibility during coding).

Note: When you look at your new project home page, it resembles a standard Git repository. However, because GitLab natively embeds a CI/CD runner execution engine, it is designated as a "Project" rather than just a plain repository.

2. Core Mental Model: How GitLab CI/CD Works

To understand how GitLab automates your software delivery, you must understand the structural hierarchy of a pipeline.

Real-Life Analogy: The Assembly Line Factory

Think of a GitLab CI/CD Pipeline as an automated industrial assembly line in a manufacturing plant:

• The Pipeline: The entire factory floor where raw materials enter and finished products roll out.
• The Stages: Sequential departments in the factory (e.g., Department 1: Building, Department 2: Testing, Department 3: Packaging). Each department must finish its work before the product moves to the next department.
• The Jobs: Individual workstations or workers inside those departments carrying out specific tasks (e.g., a worker running a unit test suite, another linting code).
• The Script / Commands: The exact instruction manual or toolset the worker uses at their desk.

Pipeline Architecture Hierarchy

3. The Anatomy of .gitlab-ci.yml

GitLab discovers how to build, test, and deploy your project by reading a specific configuration file placed at the root of your repository:

This file must be written in YAML (YAML Ain't Markup Language) format. It defines the structure, execution order, stages, and specific shell commands that the GitLab Runner will execute.

Key Components of a CI/CD YAML File:

1. stages: Globally defines the chronological phases through which the pipeline flows. Stages run sequentially (one after another).
2. Job Definition (e.g., my_job): A custom-named block representing a discrete task. Every job must be assigned to one of the defined stages.
3. script: The core execution block containing standard Bash commands (echo, Python scripts, shell scripts, Maven/Gradle commands) executed sequentially by the runner shell.

4. Writing Your First Basic Pipeline Configuration

Let's write a simple pipeline configuration containing three distinct stages (my_build_stage, my_test_stage, and an implied or explicit test phase) with one job per stage.

# Define the global execution order of stages in the pipeline
stages:
  - my_build_stage
  - my_test_stage
  - my_deploy_stage

# Job 1: Associated with the build stage
my_first_job:
  stage: my_build_stage
  script:
    - echo "My Job from Stage 1 (Build)"

# Job 2: Associated with the test stage
my_second_job:
  stage: my_test_stage
  script:
    - echo "My Job from Stage 2 (Test)"

# Job 3: Associated with the deploy stage
my_third_job:
  stage: my_deploy_stage
  script:
    - echo "My Job from Stage 3 (Deploy)"

5. Adding the Configuration via GitLab Pipeline Editor

The safest and most robust way to add or edit your .gitlab-ci.yml file is directly inside GitLab's web interface using the built-in Pipeline Editor.

Step-by-Step Implementation:

1. Navigate to your project in GitLab.
2. Click on Build -> Pipeline editor in the left-hand navigation panel.
3. If no configuration file exists, GitLab will prompt you to create a .gitlab-ci.yml file.
4. Paste your YAML configuration.

Industry Best Practice: Always use the GitLab Pipeline Editor UI rather than raw file uploads. The editor provides real-time syntax validation (Pipeline syntax is correct), instantly catching indentation errors, typos, or missing keyword declarations before you commit.

5. Enter a commit message (e.g., Add initial .gitlab-ci.yml pipeline configuration) and click Commit changes to save it to your main branch.

6. Triggering and Visualizing Your First Pipeline

Once committed, GitLab automatically detects the .gitlab-ci.yml file and schedules a pipeline run.

How to Manually Trigger a Pipeline:

1. Go to the left sidebar and click Build -> Pipelines.
2. Click the Run pipeline button in the top right corner.
3. Select your target branch (e.g., main).
4. Click Run pipeline to initiate execution.

Visualizing Execution States:

Once running, GitLab renders a clean graphical pipeline graph showing your defined stages and jobs side-by-side.

• Blue Spinner Icon: The job is currently running.
• Green Checkmark Icon: The job has passed successfully.
• Red Cross Icon: The job failed (due to syntax errors, failing tests, or missing runner configurations).

7. Inspecting Job Logs and Debugging Output

If a job fails or if you want to inspect what commands were executed by the runner, you can drill down directly into the job logs.

Accessing Job Logs:

1. Click on any job box inside the pipeline visualizer graph (e.g., click my_second_job).
2. GitLab opens the live execution console showing the complete shell output.

Running with gitlab-runner 15.x.x
Preparing the "shell" executor
Using Shell executor...
Executing "section_start" ...
$ echo "My Job from Stage 2 (Test)"
My Job from Stage 2 (Test)
Cleaning up project directory and file based variables
Job succeeded

Note: The initial lines preceding your echo statement show runner environment preparation, workspace cloning, and cleanup phases. As a beginner, you can temporarily ignore these setup headers and focus on the output of your custom script: commands.

8. Scaling Up: Adding Multiple Jobs to a Single Stage

As your projects grow, a single stage will often need to execute multiple parallel jobs simultaneously. For instance, your build stage might need to compile code for multiple environments, or your test stage might need to run unit tests and security scans in parallel.

Multi-Job YAML Configuration Example:

To add a second job to a stage, simply define a new unique job name and map it to the existing stage name.

stages:
  - my_build_stage
  - my_test_stage

# Job 1 in Build Stage
my_build_job_1:
  stage: my_build_stage
  script:
    - echo "My Job 1 from Build Stage"

# Job 2 in Build Stage (Runs in parallel with Job 1)
my_build_job_2:
  stage: my_build_stage
  script:
    - echo "My Job 2 from Build Stage - Additional Compilation"

# Job in Test Stage
my_test_job:
  stage: my_test_stage
  script:
    - echo "My Job from Test Stage"

Visual Representation of Parallel Jobs:

9. Essential GitLab CI/CD Documentation Reference

To master pipeline authoring beyond the basics, consult official GitLab reference manuals:

Summary and Key Takeaways

• Projects as Unified Workspaces: GitLab projects combine traditional Git version control repositories with native CI/CD pipeline orchestration engines.
• The YAML Specification: Pipelines are fully defined using a mandatory root-level configuration file named .gitlab-ci.yml.
• Hierarchical Structure: Pipelines are broken down sequentially into Stages, which in turn contain one or more Jobs executed in parallel or series.
• The script Keyword: Jobs utilize the script array to execute native Bash commands, shell scripts, or language-specific runtimes (Python, Node.js, Java).
• Pipeline Editor Utility: Always utilize the built-in web Pipeline Editor to catch syntax and indentation errors before committing changes.
• Visual Dashboards: GitLab provides clear visual graphs allowing developers to monitor execution statuses (Running, Passed, Failed) in real time.
• Granular Job Logs: Clicking on individual jobs grants immediate access to runner shell logs for debugging script outputs and resolving failures.
• Parallel Execution: Multiple jobs can be assigned to the exact same stage name to run concurrent tasks and speed up overall pipeline execution times.