Configure Task Dependencies and Execution Order

This document introduces how to control the execution order of multiple Jobs using needs and stages, achieving serial dependencies, parallel execution, and DAG topology orchestration.

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

Prerequisites

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

Quick Example

Method 1: Using needs Configuration

name: pipeline-with-needs

on:
  push:
    branches:
      - main

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

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

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

Method 2: Using stages Mechanism

name: pipeline-with-stages

on:
  push:
    branches:
      - main

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

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

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

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

Configuration Description

needs Dependency Mechanism

The needs configuration defines dependencies between jobs:

• The current job is executed only after the dependent job completes.
• The current job is executed only after all dependent jobs complete in parallel.
• By default, the current job does not execute if the dependent job fails (unless configured with if: ${{ always() }}).

Serial dependency example:

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

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

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

Multi-dependency aggregation example:

jobs:
  lint:
    name: Code Check
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Run check
        run: echo "lint"

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

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

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

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

Corresponding topology diagram:

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

stages Stage Mechanism

stages is a unique workflow-level structure in AtomGit Action:

• Serial execution between stages: The next stage starts only after all jobs in the previous stage complete.
• Parallel execution within a stage: Multiple jobs within the same stage are executed 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 do not execute.

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_2:
        name: codescan
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - name: sca
            run: |
              python3 codescan_gitcode.py
      static_2:
        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 Serial + Parallel Within Stage
Failure Strategy	If the dependent job fails, downstream jobs do not execute by default	fail_fast controls behavior within and across stages
Applicable Scenarios	Fine-grained dependency orchestration	Large-stage grouping and serial execution

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