How to Use needs for a DAG Pipeline in GitLab CI

The needs: keyword lets a job start the moment its specific upstream jobs finish, ignoring strict stage boundaries for faster pipelines.

Add needs: [job] to make a job depend on individual jobs rather than a whole stage. GitLab runs the resulting directed acyclic graph, shortening the critical path.

Start jobs early with needs

The deploy job runs as soon as build finishes, without waiting for the slow e2e test in the same earlier stage.

stages: [build, test, deploy]

build:
  stage: build
  script: [npm run build]
  artifacts:
    paths: [dist/]

e2e:
  stage: test
  script: [npm run test:e2e]

deploy:
  stage: deploy
  needs: [build]
  script: [./deploy.sh dist/]

Gotchas

• A job can only needs: jobs in the same or earlier stages.
• Listing a job in needs: also downloads its artifacts; set artifacts: false per entry to skip that.
• An empty needs: [] starts a job immediately, before any stage.

Key takeaways

• needs: builds a DAG so jobs start when their inputs are ready.
• It overrides strict stage ordering to shorten the critical path.
• needs entries also pull artifacts unless you disable it.

Related guides