Parallel Steps

GitHub Actions runs the steps of a job in sequence. The background keywords change this. The model is the shell: background: true is &, and wait is wait.

This document obeys ASD-STE100 Simplified Technical English. Write all prose that you add to it in the same style.

Procedure

1. Map the dependencies

Read the workflow file. For each step, find the steps that must complete before it. A step depends on a different step when it reads that step's files, outputs, or services. Done when each step has a list of the steps it depends on. An empty list is permitted.

2. Apply the keywords

Change the steps by their role:

• Independent group. Put steps with no dependencies between them in one parallel block.
• Service. A server, a database, or an emulator: give the step an id and set background: true. Add a cancel: <id> step after the last step that uses the service.
• Side task. A step that no different step reads, such as a telemetry upload: set background: true. Do not add wait.
• Reader. A step that reads the result of a background step: add a wait: <id> step before it. To wait for all the background steps that came before, use wait-all in place of wait.

Done when each background step has a wait or cancel reference. A side task with no reader needs neither.

3. Verify the workflow

Run actionlint on the file if the tool is installed. actionlint does not support these keywords yet (rhysd/actionlint#693), so it can report an error or a warning on a background, wait, wait-all, cancel, or parallel step that agrees with the reference. Ignore those messages. Read the changed workflow again. Make sure that no step reads data from a background step without a wait between them. Report the steps that stay in sequence and the reason for each.

Keywords

Keyword	Effect
background: true	Starts the step and continues to the next step immediately.
wait: <id>	Stops until the referenced steps complete. Accepts one id or a list of ids.
wait-all:	Stops until all the background steps before this point complete.
cancel: <id>	Stops the named background step without an error.
parallel:	Runs a group of steps as background steps, then waits for all of them.

For the full behavior of each keyword - concurrency limits, output availability, failure rules, and composite-action restrictions - see references/keywords.md.

Example: service

steps:
  - name: Start test server
    id: server
    run: npm run start
    background: true
  - name: Run E2E tests
    run: npm run e2e
  - name: Stop server
    cancel: server

Example: independent group

steps:
  - parallel:
      - name: Build the app
        run: npm run build
      - name: Build the docs
        run: npm run docs
  - name: Package
    run: npm run package

<!-- vale ai-tells.ParallelStaccato = NO --> <!-- The rule reads the conditional below as the second half of a staccato pair. This document also obeys ASD-STE100, which mandates the short sentences the rule flags. -->

The workflow syntax reference is the source of truth for these keywords. If a keyword does not agree with this document, obey the reference.

<!-- vale ai-tells.ParallelStaccato = YES -->