Gitlab Pipeline – stage – What is stage in GitLab CI/CD?

These keywords are fundamental for defining the structure and execution order of your CI/CD pipeline.

• stages (Global): A top-level keyword that defines all possible stages in your pipeline and their order of execution.
• stage (Job-level): A keyword used within a job definition to assign that job to one of the globally defined stages.

Example .gitlab-ci.yml with stages and stage:

YAML

# .gitlab-ci.yml

# 1. Global 'stages' definition:
# Defines the sequence of stages in the pipeline.
# Jobs in earlier stages must complete successfully before jobs in later stages can start.
stages:
  - build_assets  # First stage
  - run_tests     # Second stage
  - deploy_app    # Third stage

default:
  image: alpine:latest # Using a lightweight default image for our jobs

# --- Jobs for the 'build_assets' stage ---
compile_code:
  stage: build_assets # 2. Assigning this job to the 'build_assets' stage
  script:
    - echo "--- Compiling Code (Stage: build_assets) ---"
    - sleep 5 # Simulate work
    - echo "Code compilation complete."

package_application:
  stage: build_assets # This job is also in the 'build_assets' stage
  script:
    - echo "--- Packaging Application (Stage: build_assets) ---"
    - sleep 7 # Simulate work
    - echo "Application packaging complete."

# --- Jobs for the 'run_tests' stage ---
unit_tests:
  stage: run_tests # Assigning this job to the 'run_tests' stage
  script:
    - echo "--- Running Unit Tests (Stage: run_tests) ---"
    - sleep 10 # Simulate work
    - echo "Unit tests PASSED."

integration_tests:
  stage: run_tests # This job is also in the 'run_tests' stage
  script:
    - echo "--- Running Integration Tests (Stage: run_tests) ---"
    - sleep 12 # Simulate work
    - echo "Integration tests PASSED."
    # - exit 1 # Uncomment this line to simulate a test failure and see subsequent stages not run

# --- Job for the 'deploy_app' stage ---
deploy_to_production:
  stage: deploy_app # Assigning this job to the 'deploy_app' stage
  script:
    - echo "--- Deploying to Production (Stage: deploy_app) ---"
    - sleep 8 # Simulate work
    - echo "Deployment to production successful!"
  when: on_success # Default, but good to be explicit for deploy jobs

Code language: PHP (php)

Explanation:

1. Global stages Definition:
   • stages: at the top level of your .gitlab-ci.yml file lists all the stages your pipeline will have.
   • Order Matters: The order in which you list the stages here dictates the sequence of execution for the entire pipeline.
     • In this example: build_assets will run first, then run_tests, and finally deploy_app.
   • If this global stages list is not defined, GitLab CI defaults to a set of predefined stages (build, test, deploy), and if a job doesn’t specify a stage, it defaults to test. However, it’s a strong best practice to always define your stages explicitly for clarity and control.
2. Job-Level stage: Keyword:
   • Inside each job definition (e.g., compile_code, unit_tests), the stage: keyword assigns that job to one of the stages previously listed in the global stages definition.
   • A job must belong to a stage that is defined in the global stages list. If you assign a job to a stage not listed globally, you’ll get a linting error.
3. Execution Flow:
   • Within a Stage (Parallel Execution):
     • All jobs belonging to the same stage can run in parallel if enough GitLab Runners are available.
     • For example, compile_code and package_application are both in the build_assets stage. They can start simultaneously.
     • Similarly, unit_tests and integration_tests (both in run_tests) can run in parallel.
   • Between Stages (Sequential Execution):
     • A stage will only start after all jobs in the preceding stage have completed successfully.
     • The run_tests stage (containing unit_tests and integration_tests) will only begin after both compile_code AND package_application from the build_assets stage have finished successfully.
     • The deploy_app stage (with deploy_to_production) will only begin after both unit_tests AND integration_tests from the run_tests stage have finished successfully.
   • Job Failure Impact:
     • If any job in a stage fails, by default:
       • No new jobs will start in that stage (though currently running parallel jobs in the same stage will continue unless interruptible is used or they depend on the failed job via needs).
       • All subsequent stages will be skipped, and the pipeline will be marked as failed.
       • In the example, if integration_tests fails (e.g., by uncommenting exit 1), the deploy_to_production job in the deploy_app stage will not run.
4. default: Section:
   • default: image: alpine:latest is just setting a default Docker image for all jobs to keep the example concise. It’s not directly related to staging but is good practice.

Benefits of Using Stages:

• Control Flow: Clearly defines the order of operations in your CI/CD process.
• Logical Grouping: Groups related tasks together (e.g., all build activities, all testing activities).
• Efficiency: Allows for parallel execution of independent tasks within the same phase of your pipeline.
• Failure Management: Prevents later stages (like deployment) from running if earlier critical stages (like testing) fail.
• Readability: Makes the pipeline structure easier to understand.

By defining stages and assigning jobs to them using stage:, you create a structured, ordered, and manageable workflow for your GitLab CI/CD pipelines.