Jobs, Stages, Scripts, Images, Services, before_script, after_script, and Exit Behavior: Configuration, Design Choices, and Tradeoffs

1. Stages versus needs: barrier scheduling versus explicit dependency edges

Stages are simple: every successful job in an earlier stage forms a barrier before the next stage. This is easy to read and is a good default for small pipelines. needs expresses specific dependency edges and can start downstream work earlier, reducing critical-path latency.

Chapter 09 covers DAG engineering in depth. In Chapter 03, the operational rule is enough: do not add needs merely for speed until you can name the exact data/control dependency it replaces.

2. Default hooks versus job-local hooks

default:
  before_script:
    - ./ci/common-preflight.sh
  after_script:
    - ./ci/common-summary.sh

special_job:
  before_script:
    - ./ci/special-preflight.sh
  script:
    - ./ci/run-special.sh
  after_script: []

Defaults reduce duplication, but job-level hook configuration replaces the default for that keyword rather than merging line by line. A default hook is appropriate when every inheriting job truly shares the same precondition. Job-local hooks are safer when setup has different privilege, network, or toolchain requirements.

3. Rich prebuilt image versus runtime installation

For production, prefer an image whose human-readable version and immutable digest can be traced to a reviewed source. A tag such as alpine:3.22.1 is easier to understand than latest, but tags remain registry references and can be mutable; digest pinning gives stronger identity when operationally practical.

4. Entrypoint design is part of the image contract

Docker executor expects the image to accept the Runner-generated shell script. GitLab documents that the image needs a supported shell in PATH and grep. An image whose ENTRYPOINT insists on starting a server or exits without accepting sh/bash can break job startup.

tool_job:
  image:
    name: example.invalid/tool-image:1.4.2
    entrypoint: [""]
  script:
    - tool --version

The empty entrypoint is a deliberate compatibility override, not a universal fix. First verify the upstream image contract and trust. Do not blindly neutralize security or initialization logic embedded by the image maintainer.

5. Service container versus external dependency

A service should be disposable with the job. If multiple pipelines depend on durable mutable shared state, call that an external integration and manage its identity/authorization separately.

6. Shell portability versus convenience

Runner supports several shells. Unix jobs commonly use Bash or sh; Windows paths commonly use PowerShell variants. Syntax that is valid in Bash may fail in POSIX sh, and PowerShell has different error and quoting rules. Decide the shell contract deliberately.

portable_sh_job:
  image: alpine:3.22.1
  script:
    - set -eu
    - value="synthetic"
    - printf '%s
' "$value"

bash_specific_job:
  image: bash:5.2.37-alpine3.22
  script:
    - set -euo pipefail
    - printf 'bash=%s
' "$BASH_VERSION"

If a script requires Bash features such as arrays or pipefail, use an image/environment that explicitly provides Bash and record that assumption instead of hoping the runner fallback happens to be Bash.

7. Failure policy: fail, allow, or classify by exit code

A failed job is valuable control information. allow_failure: true changes pipeline interpretation and should correspond to a documented policy, not a desire to hide instability. GitLab also supports allow_failure:exit_codes when only specific exits are non-blocking.

optional_probe:
  script:
    - ./ci/probe.sh
  allow_failure:
    exit_codes:
      - 42

This says “exit 42 is a recognized non-blocking condition”; it does not say all probe failures are harmless. Preserve the actual exit code and evidence.

8. Worked design scenario

A team has a 40-second lint job, a 6-minute build, and a database-backed integration test. The lint does not need build output; integration does. A reasonable progression is:

1. Keep simple stages while the pipeline is small.
2. Move lint to needs: [] only when the team wants earlier feedback and understands DAG semantics.
3. Package compiler/runtime dependencies in a versioned build image instead of installing them from the internet on every job.
4. Use a disposable database service for integration tests, with explicit readiness checks and fake lab credentials.
5. Keep deployment outside this job until artifact identity and deployment authorization are designed explicitly.

9. Anti-patterns and safer replacements

Knowledge check

Official references and version notes

• CI/CD YAML syntax reference — current stages, stage, needs, image, services, before_script, after_script, allow_failure, and timeout semantics.
• Scripts and job logs — non-zero exit behavior, multiline-command caveats, default hooks, and cancellation behavior.
• Job execution flow — Runner source preparation, cache/artifact transfer, main execution, after_script, upload, and cleanup phases.
• Docker executor — job images, service containers, runner workflow, shell requirements, entrypoints, and privilege risks.
• Run jobs in Docker containers — image/service syntax, entrypoint handling, and where scripts execute.
• Services — service aliases, networking, health checks, startup warnings, and service lifecycle.
• Runner executors and supported shells — executor isolation and shell portability boundaries.