GitLab CI/CD Guide: Pipelines, Stages, Jobs and Runners

GitLab CI/CD automates work that follows a code change, including validation, build, test, packaging, security checks, and deployment. The pipeline definition normally lives with the repository so changes to automation can be reviewed alongside application code.

Core concepts#

How a pipeline flows#

1. A code or configuration event requests a pipeline.
2. Workflow rules decide whether a pipeline should exist.
3. Job rules determine which jobs are included.
4. Eligible runners claim jobs based on tags and availability.
5. Jobs execute commands in their configured environment.
6. Artifacts and reports are collected.
7. Deployment jobs update environments after required gates.

Configuration file responsibilities#

The repository configuration defines stages, jobs, scripts, images, services, variables, dependencies, rules, artifacts, caches, environments, and retry behavior. Start small: one validation job is easier to secure and debug than a large pipeline copied from another project.

Design the first pipeline#

• Use an isolated runner or trusted hosted runner.
• Run formatting and unit tests before packaging.
• Fail fast on deterministic validation errors.
• Preserve test reports as artifacts.
• Avoid deployment until build and test behavior is stable.
• Store secrets in protected settings, not in the repository file.

Runner selection#

Runner executors provide different isolation and operational tradeoffs. A shell executor runs directly on its host and requires strong trust. Container or orchestration executors can improve isolation and reproducibility, but they still require hardened images, limited privileges, and controlled networking.

Reliability and security basics#

• Pin important images and reusable configuration.
• Use least-privilege job tokens and cloud identities.
• Protect production branches and environments.
• Limit untrusted merge-request access to secrets.
• Set job timeouts and artifact retention.
• Monitor queue time, failure rate, and runner capacity.

A good first pipeline should be predictable, observable, and easy to stop. Add packaging, scans, and deployments gradually, validating permissions and failure behavior at each step.

GitLab CI/CD documentation