Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 44 ยท GitHub Actions Basics

Jobs, Steps and Dependencies

Learn how GitHub Actions jobs run in parallel, how needs orders them, and how if, outputs, continue-on-error and timeout-minutes control a workflow.

A workflow is a list of jobs, and a job is a list of steps. That sounds simple, but almost every real workflow decision comes from the difference between the two. Steps inside one job run one after another on the same machine, so they share files and environment. Jobs, on the other hand, each get their own fresh runner and, by default, all start at the same time.

This lesson shows how to turn a pile of independent jobs into a dependency graph with needs, how to skip or force jobs with if, how data travels between steps and between jobs, and how to stop a stuck or optional piece of work from ruining the whole run. The YAML below is read-only, because GitHub Actions needs GitHub's servers. The two runnable examples are stand-ins that model the scheduling and the output passing; they are not the real runner. If you have not written a workflow yet, start with Your First Workflow.

Jobs run in parallel by default

Two jobs with no relationship start together, each on its own virtual machine:

YAML
name: CI
on: [push]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

Both jobs check out the code and install dependencies, because nothing is shared between jobs. A file written in lint does not exist in test. That isolation is the price of parallelism, and it is why caching and artifacts exist.

Inside a job it is the opposite: every step shares the working directory and the file system. A step either runs a shell command with run or calls a reusable action with uses. If a step fails (a non-zero exit code), the remaining steps are skipped unless they use a status check like if: always().

Ordering jobs with needs

needs says "do not start me until these jobs have finished successfully". Give it a single name or a list:

YAML
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - run: echo "lint"

  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "test"

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

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: echo "deploy"

GitHub reads all the needs lines and builds a graph. lint and test run together, build waits for both, and deploy waits for build. A cycle (A needs B, B needs A) is rejected when the workflow is validated.

flowchart LR
  L["lint"] --> B["build"]
  T["test"] --> B
  B --> D["deploy"]

A diamond-shaped graph: two independent checks feed one build, then a deploy.

If a job in needs fails or is skipped, the dependent job is skipped too. That is usually what you want: do not deploy when tests fail. It is also the reason a cleanup or notification job needs an explicit condition.

Conditions with if

An if on a job or a step decides whether it runs. The expression language is covered in Expressions and Contexts; here are the patterns you will use first:

YAML
jobs:
  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "only on main"

  notify:
    needs: [build, deploy]
    if: ${{ always() }}
    runs-on: ubuntu-latest
    steps:
      - run: echo "build was ${{ needs.build.result }}"

Every if has an invisible success() in front of it. That means "all earlier things succeeded". When you write always(), you replace that default, so the job runs even after a failure or a cancellation. failure() runs only when something earlier failed, which is good for alerts.

The needs.<job>.result value is one of success, failure, cancelled or skipped. Use it when a job must react differently depending on how a dependency ended.

Passing data between steps

Steps in one job can hand values to later steps by writing name=value lines to the file whose path is in the GITHUB_OUTPUT environment variable. Give the writing step an id, then read it through the steps context:

YAML
steps:
  - id: version
    run: echo "number=1.4.2" >> "$GITHUB_OUTPUT"

  - run: echo "Building version ${{ steps.version.outputs.number }}"

The older ::set-output command is deprecated and should not appear in new workflows. For a value with several lines, use a delimiter:

YAML
- id: notes
  run: |
    {
      echo "text<<EOF"
      git log -3 --pretty=%s
      echo "EOF"
    } >> "$GITHUB_OUTPUT"

Two sibling files work the same way: GITHUB_ENV adds an environment variable for later steps, and GITHUB_PATH prepends a directory to PATH.

Passing data between jobs

A step output only lives inside its job. To use it in another job, promote it to a job output, then read it through the needs context:

YAML
jobs:
  prepare:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.number }}
    steps:
      - id: version
        run: echo "number=1.4.2" >> "$GITHUB_OUTPUT"

  package:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - run: echo "Packaging ${{ needs.prepare.outputs.version }}"
sequenceDiagram
  participant S as Step (id: version)
  participant J as Job prepare
  participant N as Job package
  S->>J: writes number=1.4.2 to GITHUB_OUTPUT
  J->>N: outputs.version, read as needs.prepare.outputs.version

A value is written by a step, exposed by the job, and read by a dependent job.

Outputs are for small strings such as versions, tags and file names. Large data belongs in an artifact. Never put a secret in an output: GitHub refuses to pass values it recognises as secrets between jobs.

Surviving failure: continue-on-error and timeouts

Some work is allowed to fail. continue-on-error: true on a step marks the step as failed in the log but lets the job carry on and succeed. On a job, it lets dependent jobs run as if the job had passed. Use it for experimental checks, such as testing against an unreleased runtime:

YAML
jobs:
  experimental:
    runs-on: ubuntu-latest
    continue-on-error: true
    steps:
      - run: ./try-the-nightly-build.sh

The opposite problem is work that never ends. A job can run for up to 6 hours by default, which wastes minutes if a test hangs. Set timeout-minutes on jobs, and on single steps that are known to be risky:

YAML
jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - run: npm test
        timeout-minutes: 10

A short, realistic timeout (a few times the normal run time) is one of the cheapest reliability settings you can add.

Stand-in: scheduling jobs in waves

GitHub's scheduler is not public code, but the idea is the standard topological ordering. In each round, every job whose dependencies are all finished can start. The model below groups the jobs into those rounds, skips jobs whose dependency did not succeed, and lets a job with always run anyway. Change the fails list to see the effect.

JS Model of the needs scheduler

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With test failing, build and deploy are skipped, but notify still runs because it has the equivalent of if: always(). The workflow as a whole is reported as failed.

Stand-in: step outputs and job outputs

This second model writes name=value lines the way a step writes to GITHUB_OUTPUT, parses them, and then exposes only the values a job lists under outputs. It shows why a step output is invisible to other jobs until you promote it.

JS From GITHUB_OUTPUT to needs outputs

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second step output, temp, never leaves the job. Only the promoted version can be read as needs.prepare.outputs.version.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Two jobs in one workflow have no needs. What happens?

    Jobs run in parallel by default, each on a fresh runner. Only needs creates an order, and only steps inside a job share the machine.
  2. 2. Job deploy has needs: test, and test fails. What happens to deploy?

    A job whose dependency did not succeed is skipped, unless its if condition (for example always()) says otherwise.
  3. 3. How can job B read a value that a step in job A computed?

    Step outputs live inside their job. A job outputs entry exposes the value, and the dependent job reads it through the needs context.
  4. 4. What is the purpose of timeout-minutes?

    Without a limit a hung job can run for hours and burn billable minutes. A realistic timeout turns that into a quick failure.

Summary

  • Jobs run in parallel on separate runners; steps in one job run in order on the same machine.
  • needs builds a dependency graph; a job whose dependency failed or was skipped is skipped.
  • if conditions start with an implicit success(); use always() or failure() for cleanup and alerts, and needs.<job>.result to inspect outcomes.
  • Steps pass values by appending name=value to GITHUB_OUTPUT; jobs expose them with outputs and others read needs.<job>.outputs.<name>.
  • continue-on-error tolerates optional failures, and timeout-minutes stops runaway jobs.

Next: Expressions and Contexts