GitHub Actions Parallel Steps: Use background, wait, and parallel

Choose between parallel and background#

The two forms solve related but different timing problems:

Each job can run at most 10 background steps concurrently. A parallel group uses the same limit because it is shorthand for background steps followed by a wait.

Run independent work with parallel#

This is the compact form for independent build commands:

1
name: Build components
2

3
on:
4
  push:
5

6
jobs:
7
  build:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - uses: actions/checkout@v6
11

12
      - parallel:
13
          - name: Build frontend
14
            run: npm run build:frontend
15
          - name: Build backend
16
            run: npm run build:backend
17
          - name: Build documentation
18
            run: npm run build:docs
19

20
      - name: Run integration tests
21
        run: npm test

The three build steps start concurrently, and the test step starts only after all three succeed. Keep the group independent: do not put a step in it that expects another parallel step to have already created a file, migrated a database, or reserved a port.

parallel does not create separate jobs or separate runners. The steps share the job’s working directory and environment, so simultaneous writes to the same output directory can still race. Give each command an isolated output path or use separate jobs when the work needs independent runners, permissions, or operating systems.

Keep a server alive with background and wait#

For a test server, start it asynchronously and keep the ID so a later step can synchronize with it:

1
steps:
2
  - uses: actions/checkout@v6
3

4
  - name: Start preview server
5
    id: preview
6
    run: npm run preview
7
    background: true
8

9
  - name: Run browser tests
10
    run: npm run test:e2e
11

12
  - name: Wait for preview server
13
    wait: preview

wait performs no command of its own. It blocks until the referenced background step finishes, then makes that step’s outputs and environment changes available to subsequent steps. If the background process fails, the wait step fails too. For a real server that is expected to remain alive until the job ends, the test command should stop it or the workflow should use cancel in cleanup; a server that never exits will otherwise keep the wait pending.

When several services need to start together, use wait-all:

1
steps:
2
  - name: Start database
3
    id: database
4
    run: docker run --rm --name ci-db postgres:15
5
    background: true
6

7
  - name: Start cache
8
    id: cache
9
    run: docker run --rm --name ci-cache redis:7
10
    background: true
11

12
  - name: Run integration tests
13
    run: npm run test:integration
14

15
  - name: Wait for services
16
    wait-all:

Use a health check in the test setup if the service needs time to accept connections. Parallel execution starts processes together; it does not prove that a database is ready.

Wait for selected steps and inspect failures#

Use a list when the next step depends on a subset of the background work:

1
steps:
2
  - name: Build frontend
3
    id: frontend
4
    run: npm run build:frontend
5
    background: true
6

7
  - name: Build backend
8
    id: backend
9
    run: npm run build:backend
10
    background: true
11

12
  - name: Run lint while builds run
13
    run: npm run lint
14

15
  - name: Wait for both builds
16
    wait: [frontend, backend]
17

18
  - name: Package release
19
    run: npm run package

Do not assume that a background step’s output is ready just because its process has started. Read outputs after the corresponding wait or wait-all. This matters when a step writes a generated path to $GITHUB_OUTPUT or updates the job environment.

For a long-running monitor or service, cancel it after the main task:

1
steps:
2
  - name: Start monitor
3
    id: monitor
4
    run: ./scripts/monitor.sh
5
    background: true
6

7
  - name: Run the main task
8
    run: npm test
9

10
  - name: Stop monitor
11
    cancel: monitor

cancel sends a termination signal and gives the process a short chance to clean up before forcing it to stop. The cancel step always runs as a workflow control operation; design the monitored command so its logs and exit status remain useful.

Why shell backgrounding is a weaker fallback#

This older pattern hides the process from the Actions step model:

1
npm run preview &
2
npm test

The shell may report success from the foreground command while the preview process fails later. Cleanup also depends on custom PID handling, and the logs from the two processes are mixed. If the project must support an older runner without the new workflow syntax, use a small, tested process supervisor and explicit health checks; do not treat & as a replacement for workflow-managed synchronization.

The new keywords are step-level features. They are not a reason to move every command into one large job: use a matrix or separate jobs when each environment needs independent isolation, and use needs when jobs—not steps—have a dependency.

The reusable workflow secrets guide covers a different boundary: passing configuration between jobs and workflows. This article is about scheduling steps inside one job. If a parallel build also fails because the action runtime changed, see actions/checkout v5 and Node24.

Verify a parallel workflow safely#

Before merging, check the workflow in a small branch or manual run:

1. Start with two commands that write separate files and confirm they overlap in the logs.
2. Make one background or parallel command exit non-zero and confirm the correct wait or implicit group wait fails.
3. Make a background server fail before tests and confirm the failure is not hidden by a successful foreground command.
4. Confirm generated outputs are not written to the same path concurrently.
5. Confirm cleanup runs for servers, databases, and monitors.
6. Keep step IDs unique and use wait only for steps marked background: true.

The practical rule is to make the dependency visible in YAML: parallel for independent work that ends together, background plus wait for a process that must remain available, and cancel for deliberate cleanup.

FAQ#