Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท GitLab CI/CD Pipelines

Stages, Jobs and Job Ordering

Control how GitLab CI jobs run: stages, .pre and .post, when, allow_failure, manual jobs, retry, timeout, parallel jobs, hidden jobs and extends.

In the previous lesson you wrote a pipeline with a few jobs. Real pipelines need more control: some jobs should only run when an earlier one failed, some may fail without stopping the pipeline, some need a human click, and many jobs share the same settings. This lesson covers the keywords that shape how jobs are ordered and when they run.

How stages execute

The pipeline walks through stages from top to bottom. For each stage, GitLab starts all of its jobs (as runners become free). When every job in the stage has finished successfully, the next stage begins. If a job fails, the pipeline stops after that stage and later stages are skipped, unless the failed job is allowed to fail.

Two special stages exist without you declaring them:

  • .pre always runs first, before the first stage you declared.
  • .post always runs last.

They are useful for setup (checking that variables exist) and cleanup or notifications.

The stand-in below simulates the stage rules: stages in order, jobs in a stage together, a failure stopping later stages, and allow_failure letting a pipeline continue. It reads a real configuration with a YAML parser. The job outcomes are given by a simple table, since there is no real runner here.

Python Stand-in: simulate how a pipeline walks through stages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that a failing lint shows a warning but the pipeline still reaches the deploy stage, while a failing unit test makes deploy-prod skipped.

When a job runs: when

The when keyword decides when a job is eligible:

  • on_success (default): run only if all jobs in earlier stages succeeded.
  • on_failure: run only if a job in an earlier stage failed. Good for sending an alert.
  • always: run regardless of earlier results. Good for cleanup.
  • manual: wait for a person to click play. Good for production deploys.
  • delayed: run after a delay given by start_in.
  • never: do not run (used inside rules).
YAML
notify-failure:
  stage: .post
  script:
    - echo "A job failed, notifying the team"
  when: on_failure

deploy-production:
  stage: deploy
  script:
    - ./deploy.sh production
  when: manual

A manual job is by default allowed to fail (the pipeline continues without waiting). To make the pipeline wait for the click, set allow_failure: false on the manual job. That is the standard way to build an approval gate in front of production.

allow_failure, retry and timeout

YAML
flaky-ui-tests:
  stage: test
  script: ./run-ui-tests.sh
  allow_failure: true          # show a warning, do not fail the pipeline
  retry:
    max: 2                     # up to 2 automatic retries
    when:
      - runner_system_failure
      - stuck_or_timeout_failure
  timeout: 20 minutes          # fail the job if it runs longer
  • allow_failure: true is for informational jobs such as linters you are still rolling out. Also accepts exit_codes, so only certain codes count as allowed.
  • retry re-runs a job automatically. Retrying on infrastructure failures is reasonable; retrying on every script failure hides flaky tests, so be careful.
  • timeout limits a job's runtime. The project default is 1 hour, and a runner may enforce a lower cap.
  • interruptible: true marks a job as safe to cancel when a newer commit makes the pipeline obsolete (combine with automatic cancellation of redundant pipelines).
  • resource_group: production makes jobs with the same group name run one at a time, which prevents two deployments to the same place from racing.

Parallel jobs

parallel runs several copies of one job, useful for splitting a long test suite:

YAML
tests:
  stage: test
  script:
    - ./run-tests.sh --shard $CI_NODE_INDEX/$CI_NODE_TOTAL
  parallel: 4

Each copy gets CI_NODE_INDEX (1 to 4) and CI_NODE_TOTAL (4). The parallel:matrix form creates one job per combination of values, for example testing on several language versions. The needs lesson shows how to expand a matrix.

Reusing settings: hidden jobs, extends and anchors

Job names starting with a dot are hidden: GitLab never runs them, so they work as templates. A job pulls in a template with extends:

YAML
.node-job:
  image: node:22
  before_script:
    - npm ci

unit-tests:
  extends: .node-job
  stage: test
  script:
    - npm test

lint:
  extends: .node-job
  stage: test
  script:
    - npm run lint

extends merges hash keys (a job's own keys win) but replaces lists such as script entirely. YAML anchors (&name and *name) give a similar effect inside one file, and !reference [.setup, script] lets a job reuse part of another job, such as one of its lists.

The stand-in below mimics how extends merges a template into a job: dictionaries merge with the job winning, and any list is replaced rather than appended.

Python Stand-in: how extends merges a template

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

You will see variables merged key by key (with NODE_ENV taken from the job), while before_script is replaced as a whole.

Debugging order problems

  • A job is skipped: an earlier job failed, or its rules excluded it.
  • A job is stuck pending: no runner matches its tags (see runners overview).
  • A deploy ran too early: check its stage and whether needs lets it start sooner.
  • Two deploys overlapped: add a resource_group.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which stages exist even if you do not declare them?

    .pre runs before your first stage and .post after your last, when jobs are assigned to them.
  2. 2. What does when: on_failure do?

    on_failure jobs run when at least one job in an earlier stage failed, for example to send an alert.
  3. 3. How do you make a pipeline wait for a person to approve a manual production job?

    Manual jobs are allowed to fail by default (the pipeline does not wait). Setting allow_failure: false makes it a real gate.
  4. 4. A template job extends .node-job and defines its own script. What happens to the template's script list?

    extends deep-merges hashes but replaces arrays; the job's own values win.

Summary

  • Stages run in order; jobs inside a stage run in parallel; a failure stops later stages.
  • when, allow_failure, retry, timeout and resource_group refine when and how a job runs.
  • Manual jobs plus allow_failure: false make approval gates.
  • parallel splits work across copies of a job.
  • Hidden jobs, extends, anchors and !reference remove copy-paste from your config.

Next: Variables and Rules