Configuring 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 achieve 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 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 Instructions

needs Dependency Mechanism

needs configures dependencies between jobs:

• The current job is executed only after the dependent job is completed.
• The current job is executed only after all dependent jobs are completed in parallel.
• If the dependent job fails, the current job does not execute by default (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"

Multiple dependencies 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 are completed.
• Parallel execution within a stage: Multiple jobs within the same stage run in parallel.
• fail_fast: When a job in the 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 run.

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 Policy	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 dependency relationships using needs.