Build a pipeline you can actually trust

01. Define what green means

A passing pipeline is only useful when the team understands what it proves. Does it show that the application builds? That tests pass? That a release can be deployed? Write that promise down before adding more jobs.

For a small project, start with a modest promise: the repository’s automated checks pass and the resulting package is available for inspection. A successful package job does not prove the application is healthy in production.

In GitLab, jobs describe work and stages group it. In a basic stage-based pipeline, later stages normally wait for earlier stages to succeed. More advanced dependencies can change that scheduling; begin with the simplest structure that fits.

02. Start with two clear stages

This small example assumes a Python project with application files under src/, existing unittest tests under tests/, and no third-party dependencies. Put it in .gitlab-ci.yml. An eligible GitLab runner must be available.

image: python:3.13-slim

stages:
  - test
  - package

unit_tests:
  stage: test
  script:
    - python -m unittest discover -s tests -v

package_app:
  stage: package
  script:
    - mkdir -p release
    - tar -czf release/app.tar.gz src/
  artifacts:
    paths:
      - release/app.tar.gz
    expire_in: 7 days

Adapt the test command and package contents to your application. Projects with dependencies need a reproducible installation step, and production pipelines should use deliberately maintained build images. This example creates an archive; it does not deploy it.

03. Keep the output connected to the change

GitLab job artifacts preserve files produced by a job, such as packages or reports. Retention is configurable, and later jobs can consume artifacts from earlier work. The artifact documentation explains the behavior and retention controls.

Record which commit, pipeline, and build process produced a release. Once you add deployment, promote the verified artifact through the intended environments. Rebuilding the same commit with changed dependencies may produce a different result.

Keep release retention separate from the seven-day example above. A rollback plan needs a known package that remains available for as long as the team intends to support it.

04. Exercise the failure path

Before trusting the pipeline, make an intentional failing test on a temporary branch. Confirm that the pipeline fails and that the packaging stage does not proceed. Then restore the test and confirm the expected artifact appears.

Read the test output and check the number of tests that actually ran. A green job that executed zero meaningful checks provides very little evidence.

Only add a deployment stage when you can describe its target, access boundary, verification step, and recovery procedure. A short pipeline that makes a clear promise is a sound base for a larger one.