← Full reference

GitHub Actions

GitHub Actions workflows — on, jobs, runs-on, steps uses/run, needs, matrix, expressions, workflow_call, actionlint

GitHub Actions runs workflows — YAML files from the .github/workflows/ directory — on repository events: push, pull request, schedule, manual run. A workflow consists of jobs, which run in parallel by default, each on its own virtual machine (runner). A job is a sequence of steps: a ready-made action (uses) or a shell command (run).

Checking in the sandbox: actionlint parses workflows and finds errors in keys, ${{ }} expressions, references between jobs, inputs of popular actions and (via shellcheck) in run scripts.

Syntax

name: CI
on: push                 # when to run
jobs:
  job_name:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo hello

Top-level keys

KeyWhat it sets
name / run-nameworkflow name / name of a specific run (expressions allowed)
ontrigger events
permissionsGITHUB_TOKEN permissions: contents: read, packages: write…
envenvironment variables for all jobs
defaults: run:shell and working-directory for all run steps
concurrencygroup and cancel-in-progress: don't run identical runs in parallel
jobsjobs

on events

EventWhen it fires
pushpush; filters branches, tags, paths, branches-ignore, paths-ignore
pull_requestPR events; types: [opened, synchronize], the same branch and path filters
workflow_dispatchmanual run via a button; inputs — form parameters
scheduleon a schedule: - cron: '0 3 * * 1' (UTC time)
workflow_callcalled from another workflow (reusable); inputs, secrets, outputs
release, issues, workflow_run…other repository events

Job keys

KeyWhat it sets
runs-onrunner: ubuntu-latest, windows-latest, macos-latest or your own runner's labels
needswhich jobs it depends on: it starts after they succeed
ifcondition for running the job
stepsthe job's steps
envvariables for all steps of the job
outputsvalues dependent jobs see via needs.<id>.outputs
strategy.matrixrun the job for every combination of values; include, exclude
strategy.fail-fast / max-parallelwhether to cancel other combinations on failure / how many at once
environmentenvironment (environment secrets, approval rules)
container / servicesrun steps in a container / start side containers (a DB)
timeout-minutes / continue-on-errortime limit / don't fail the workflow on error
uses + with + secretsinstead of steps: call a reusable workflow

Step keys

KeyWhat it sets
uses: owner/repo@versiona ready-made action; ./path — a local one
withthe action's inputs
runshell commands (multiple lines — via |)
shellbash, sh, pwsh, python
name / idlabel in the log / identifier for steps.<id>.outputs
ifcondition for running the step
envstep variables
working-directorydirectory for run
continue-on-error / timeout-minutesdon't fail the job / time limit

A single step has either uses or run.

Expressions and contexts

Expressions are written in ${{ … }}; in if the braces can be omitted.

ContextWhat it holds
githubevent and repository: github.ref, github.sha, github.event_name, github.actor, github.event.*
env / varsenvironment variables / repository variables from settings
secretssecrets: secrets.DEPLOY_TOKEN, secrets.GITHUB_TOKEN
matrixvalues of the current matrix combination
needsresults and outputs of jobs from needs
stepsoutputs and outcome of previous steps (steps.<id>.outputs.x)
inputsworkflow_dispatch / workflow_call parameters
runnerrunner info: runner.os, runner.temp
FunctionWhat it does
success(), failure(), always(), cancelled()status for if: by default a step runs only on success()
contains(a, b), startsWith(a, b), endsWith(a, b)string and list checks
format('{0}-{1}', a, b), join(list, ',')building strings
toJSON(x) / fromJSON(s)to JSON / from JSON
hashFiles('**/package-lock.json')hash of files — for cache keys

Operators: ==, !=, &&, ||, !, <, >.

Runner files

VariableWhat to write to it
$GITHUB_OUTPUTname=value — a step output (steps.<id>.outputs.name)
$GITHUB_ENVNAME=value — an environment variable for the following steps
$GITHUB_PATHa directory added to PATH for the following steps
$GITHUB_STEP_SUMMARYMarkdown for the run summary page

Examples

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci
      - run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.ver.outputs.version }}
    steps:
      - uses: actions/checkout@v4
      - id: ver
        run: echo "version=1.0.${{ github.run_number }}" >> "$GITHUB_OUTPUT"
      - name: Build
        run: |
          mkdir -p dist
          echo "built" > dist/app.txt
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
      - if: failure()
        run: echo "build failed"

A reusable workflow and how to call it:

# .github/workflows/deploy.yml
on:
  workflow_call:
    inputs:
      environment:
        type: string
        required: true
    secrets:
      token:
        required: true
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    steps:
      - run: echo "deploy to ${{ inputs.environment }}"
        env:
          TOKEN: ${{ secrets.token }}
---
# .github/workflows/release.yml
on: workflow_dispatch
jobs:
  call:
    uses: ./.github/workflows/deploy.yml
    with:
      environment: production
    secrets:
      token: ${{ secrets.DEPLOY_TOKEN }}
# check all workflows in the repository (run inside a git repository)
actionlint

# check specific files
actionlint .github/workflows/ci.yml

# sample message:
# ci.yml:6:5: unexpected key "branch" for "push" section. expected one of "branches", ... [syntax-check]

# view triggers with yq (it understands YAML 1.2 and sees the on key as a string)
yq '.on | keys' .github/workflows/ci.yml

Pitfalls

  • on in YAML 1.1 is true. GitHub and actionlint read the on key correctly, but YAML 1.1 parsers (e.g. PyYAML in Python scripts) turn it into the boolean True, and data['on'] raises KeyError. In your own scripts look up the key True or write "on": in quotes in the file. yes/no/off behave the same way in YAML 1.1.
  • actionlint without arguments looks for a git repository up the directory tree. Outside a repository it exits with no project was found — pass the file paths explicitly.
  • A workflow must live in .github/workflows/ and have a .yml or .yaml extension, otherwise GitHub won't see it.
  • A step with both uses and run is an error. Split them into two steps.
  • Misspelled keys (branch instead of branches, step instead of steps, fetch_depth instead of fetch-depth) don't give a working workflow — actionlint catches them.
  • needs.<id>.outputs are available only if the job is listed in needs and declared outputs. Otherwise the expression is empty, and actionlint warns.
  • After a step fails, the following ones are skipped. For a step to always run (cleanup, report), use if: always() or if: failure().
  • Untrusted data in run is an injection risk. ${{ github.event.pull_request.title }} is substituted into the script as text. Pass such values via env: and use them as "$TITLE".
  • schedule runs in UTC and only for the repository's default branch.
  • Pin action versions to a tag or hash (@v4), not a branch: a branch can change without warning.

See also

gitlab-ci · git · yq · shellcheck