Jobs orchestration: rules, needs, stages, and triggers
The Jobs orchestration domain tests how jobs are sequenced or deliberately unsequenced: stages, needs DAG edges, rules evaluation, manual and delayed jobs, and triggers that create child or multi-project pipelines.
Stages and needs
Stages run in order, and jobs in one stage run in parallel. needs creates a directed acyclic graph: a job can start as soon as its named dependencies finish, even if earlier stages are still running. needs: [] starts immediately. needs can name jobs in the same or earlier stages, and needs:optional tolerates a dependency that may not exist. Cycles are invalid. needs:project and needs:pipeline pull artifacts across project or pipeline boundaries when configured.
Rules and triggers
rules are evaluated top to bottom; the first matching rule wins, and no match means the job is not added. rules:if, rules:changes, and rules:exists can set when, allow_failure, variables, and needs. workflow:rules controls pipeline creation, not job inclusion. when: manual creates a gate; when: delayed waits a duration. trigger starts a child pipeline from include or a multi-project pipeline from project/branch; strategy: depend makes the parent wait and mirror the child status. Trigger jobs do not need script.
Worked example
stages: [build, test, deploy]
build:
stage: build
script: make build
artifacts:
paths: [dist/]
test:
stage: test
needs: [build]
script: make test
deploy:
stage: deploy
needs: [build, test]
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
when: manual
script: make deploy
test starts when build finishes, without waiting for other build jobs. deploy waits for both artifacts and only appears on the default branch as a manual gate. If test fails, deploy does not run. Set allow_failure explicitly if the gate must block rather than being optional.
Traps
Treating rules as last-match-wins reverses the intended logic. Using workflow:rules to try to include a job is the wrong level. A needs reference to a job excluded by rules breaks the pipeline unless marked optional. Child pipelines do not automatically share parent artifacts; use needs:project/needs:pipeline or pass inputs deliberately. only/except cannot be mixed with rules.