CI/CD YAML, Scripts, Images, Services, before_script, after_script, and Defaults: Configuration, Design Choices, and Tradeoffs

1. Defaults reduce duplication but increase change radius

default is valuable when many jobs intentionally share a contract: image, runner tags, retry policy, or setup/cleanup hooks. The risk is hidden coupling. A one-line change to a default may alter every job that does not override that key, including jobs in included configuration.

A useful design question is: if this value changes, should every inheriting job change together? If yes, a default expresses policy. If no, explicit job configuration is usually clearer.

2. Minimal trusted image versus convenience-heavy image

A tiny image can reduce attack surface, pull time, and accidental tool availability, but it may increase setup complexity or expose differences such as BusyBox versus GNU utilities. A large “CI toolbox” image improves convenience but becomes a high-value supply-chain dependency with more packages, patching work, and hidden capabilities.

Production policy should define who builds/approves CI images, where they are hosted, how they are scanned, how digests are recorded, and how updates are promoted. A digest pins identity; it does not prove the image is trustworthy. Trust comes from provenance, review, build process, vulnerability context, and controlled promotion.

3. Service sidecar versus external integration dependency

A service sidecar is ideal for disposable tests that need an isolated database, cache, or HTTP endpoint. Its lifecycle is coupled to the job and its data can be synthetic. An external test environment may better represent shared integration behavior, but it introduces network availability, credentials, concurrency, cleanup, data governance, and potentially billing.

4. Portable shell or constrained runner: make the choice explicit

Portable scripts favor common POSIX constructs and tools that are guaranteed by the selected image. Executor-specific optimization deliberately relies on Bash, PowerShell, Windows paths, Docker socket access, GPU devices, or other platform characteristics. Both can be valid; the failure is leaving the dependency implicit.

If a job requires Bash, use an image/runner where Bash is present and document that requirement. If it requires PowerShell, constrain the runner appropriately and write PowerShell syntax. Do not assume /bin/sh, Bash arrays, PowerShell cmdlets, and Windows path quoting are interchangeable.

5. Defaults and includes create a configuration dependency graph

Included files can contribute defaults that affect jobs declared elsewhere. This is powerful for standardization but can surprise maintainers when they inspect only the local YAML. Review the merged configuration in the Pipeline Editor/CI Lint when behavior seems inconsistent with the file in front of you.

For production includes, pin the source/ref where practical, review changes, and treat remote templates/components as supply-chain dependencies. Chapter 20 goes deeper into reusable pipeline architecture; here the key principle is that resolved configuration—not one physical YAML file—is what GitLab executes.

6. Worked scenario: choose a runtime policy

A team has 20 jobs: 14 use the same static-analysis image, 4 need a database for tests, and 2 build Windows binaries. Which design is preferable?

7. Decision table: production dimensions

8. Common design mistakes

• Install the world in before_script: every job pays network/time risk. Prefer a reviewed purpose-built image when setup is stable.
• Use latest everywhere: no repository diff is required for behavior to change.
• Assume services equal production: sidecars are test dependencies, not topology proof.
• Hide platform needs: Bash/PowerShell/Docker requirements should constrain runner selection visibly.
• Copy giant defaults into each job: defeats centralized policy and creates drift.
• Put secrets in image arguments or service commands: keep secret handling in the appropriate protected CI/CD secret mechanism; Chapter 13 covers it deeply.

Knowledge check

Summary

Good CI YAML makes coupling explicit. Use defaults for intentional shared policy, job overrides for scoped differences, reviewed and identifiable images for runtime reproducibility, services for bounded test dependencies, and explicit runner/shell constraints for platform-specific work. Optimize only after you can explain the resolved configuration and trust boundary.

Official references

• GitLab Docs — CI/CD YAML syntax reference
• GitLab Docs — Scripts and job logs
• GitLab Docs — Deprecated CI/CD keywords
• GitLab Docs — Use CI/CD configuration from other files
• GitLab Docs — Run CI/CD jobs in Docker containers
• GitLab Docs — Services
• GitLab Docs — Docker executor
• GitLab Docs — Shell executor
• GitLab Docs — Runner executors
• GitLab Docs — Pipeline editor
• GitLab Docs — CI Lint
• GitLab Docs — Predefined CI/CD variables
• GitLab Docs — Runner security