Configuring Task Dependencies and Execution Order

Applicable Scenarios: When you need to control the execution order of multiple jobs to implement a serial process such as build → test → deploy, or more complex DAG topologies.

Prerequisites

• The workflow contains multiple jobs.
• Understand the needs dependency and stages stage mechanism.

Quick Examples

Method 1: Using needs Configuration

name: pipeline-with-needs

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "build"

  test:
    runs-on: [ubuntu-latest, x64, small]
    needs: build
    steps:
      - run: echo "test"

  deploy:
    runs-on: [ubuntu-latest, x64, small]
    needs: test
    steps:
      - run: echo "deploy"

Method 2: Using stages Mechanism

name: pipeline-with-stages

on:
  push:
    branches:
      - main

stages:
  - name: build-stage
    fail_fast: true
    jobs:
      build:
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - run: echo "build"

  - name: test-stage
    jobs:
      unit-test:
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - run: echo "unit test"

      integration-test:
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - run: echo "integration test"

  - name: deploy-stage
    jobs:
      deploy:
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - run: echo "deploy"

Configuration Description

needs Dependency Mechanism

The needs configuration defines dependencies between jobs:

• The current job will only execute after the dependent job is completed.
• If there are multiple dependent jobs, the current job will execute only after all of them are completed.
• If the dependent job fails, the current job will not execute by default (unless configured with if: ${{ always }}).

Serial dependency example:

jobs:
  build:
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "build"

  test:
    needs: build
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "test"

  deploy:
    needs: test
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "deploy"

Multiple dependencies convergence example:

jobs:
  lint:
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "lint"

  unit-test:
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "unit test"

  integration-test:
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "integration test"

  package:
    needs:
      - lint
      - unit-test
      - integration-test
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "package"

  release:
    needs: package
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - run: echo "release"

Corresponding topology diagram:

lint ──────────┐
               │
unit-test ─────├── package ── release
               │
int-test ──────┘

stages Stage Mechanism

stages is a workflow-level structure specific to AtomGit Action:

• Sequential execution between stages: The next stage starts only after all jobs in the previous stage are completed.
• Parallel execution within a stage: Multiple jobs in the same stage run in parallel.
• fail_fast: When a job in a stage fails:
  • fail_fast: true: Immediately terminates other jobs in the current stage and skips all subsequent stages.
  • fail_fast: false: Other jobs in the current stage continue to run, but subsequent stages will not be executed.

stages:
  stage1:
    name: PR SCA
    jobs:
      sca:
        name: codescan
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - name: sca
            run: |
              python3 codescan_gitcode.py
      static:
        name: static check
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - name: static_check
            run: |
              python3 static_gitcode.py  
  stage2:
    name: Release SCA
    jobs:
      sca:
        name: codescan
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - name: sca
            run: |
              python3 codescan_gitcode.py
      static:
        name: static check
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - name: static_check
            run: |
              python3 static_gitcode.py                            

• stages can be omitted: When the workflow has only one logical stage, the stages field can be omitted.

Differences Between needs and stages

Comparison Item	needs	stages
Control Granularity	Job level	Stage level
Execution Model	DAG topology	Stage sequential + Parallel within stage
Failure Strategy	If dependent job fails, downstream jobs do not execute by default	fail_fast controls behavior within and across stages
Applicable Scenarios	Fine-grained dependency arrangement	Large stage grouping for sequential execution

Both methods can be used together: Jobs within the same stage can still use needs to configure dependencies.