needs and depends-on — declaring edges between jobs

The needs: clause declares an edge in the pipeline DAG. The current job waits for every job listed in needs: to complete before starting. The list can be a single job or many.

needs in GitHub Actions

jobs:
  build:
    runs-on: ubuntu-latest
  test:
    runs-on: ubuntu-latest
    needs: build
  package:
    runs-on: ubuntu-latest
    needs: [build, test]
  deploy:
    runs-on: ubuntu-latest
    needs: package

A single predecessor can be a bare string or a one-element list; equivalent. Multiple predecessors must be a list. Default is to wait for successful completion.

needs in GitLab CI

package:
  stage: package
  needs: [unit, integration]
  script: make package

package:
  stage: package
  needs:
    - job: unit
      artifacts: true
    - job: integration
      artifacts: true
  script: make package

The first is a simple list; the second couples needs: with the artifact download.

Single versus multiple predecessors

A list of one means “wait for this job”. A list of many means “wait for all of these jobs”. The scheduler starts the current job when every predecessor has completed.

grep -B 1 'needs:' .github/workflows/ci.yml

Implicit completion states

The default waits for successful completion only. States: success, always, failure, cancelled. GitHub Actions uses if: always(); GitLab CI uses when: on_success / when: always.

Production discipline

1. Declare needs: explicitly; absent is immediate.
2. Use bare-string form for a single predecessor.
3. Audit needs: for cycles.

Cross-course references

• Ansible for Production Sysadmins - Part XXXVII uses the same pattern in AWX workflows.
• Linux for Production Sysadmins - Part XXX uses the same edge for systemd Requires=.

Quiz