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
| Key | What it sets |
|---|---|
name / run-name | workflow name / name of a specific run (expressions allowed) |
on | trigger events |
permissions | GITHUB_TOKEN permissions: contents: read, packages: write… |
env | environment variables for all jobs |
defaults: run: | shell and working-directory for all run steps |
concurrency | group and cancel-in-progress: don't run identical runs in parallel |
jobs | jobs |
on events
| Event | When it fires |
|---|---|
push | push; filters branches, tags, paths, branches-ignore, paths-ignore |
pull_request | PR events; types: [opened, synchronize], the same branch and path filters |
workflow_dispatch | manual run via a button; inputs — form parameters |
schedule | on a schedule: - cron: '0 3 * * 1' (UTC time) |
workflow_call | called from another workflow (reusable); inputs, secrets, outputs |
release, issues, workflow_run… | other repository events |
Job keys
| Key | What it sets |
|---|---|
runs-on | runner: ubuntu-latest, windows-latest, macos-latest or your own runner's labels |
needs | which jobs it depends on: it starts after they succeed |
if | condition for running the job |
steps | the job's steps |
env | variables for all steps of the job |
outputs | values dependent jobs see via needs.<id>.outputs |
strategy.matrix | run the job for every combination of values; include, exclude |
strategy.fail-fast / max-parallel | whether to cancel other combinations on failure / how many at once |
environment | environment (environment secrets, approval rules) |
container / services | run steps in a container / start side containers (a DB) |
timeout-minutes / continue-on-error | time limit / don't fail the workflow on error |
uses + with + secrets | instead of steps: call a reusable workflow |
Step keys
| Key | What it sets |
|---|---|
uses: owner/repo@version | a ready-made action; ./path — a local one |
with | the action's inputs |
run | shell commands (multiple lines — via |) |
shell | bash, sh, pwsh, python |
name / id | label in the log / identifier for steps.<id>.outputs |
if | condition for running the step |
env | step variables |
working-directory | directory for run |
continue-on-error / timeout-minutes | don'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.
| Context | What it holds |
|---|---|
github | event and repository: github.ref, github.sha, github.event_name, github.actor, github.event.* |
env / vars | environment variables / repository variables from settings |
secrets | secrets: secrets.DEPLOY_TOKEN, secrets.GITHUB_TOKEN |
matrix | values of the current matrix combination |
needs | results and outputs of jobs from needs |
steps | outputs and outcome of previous steps (steps.<id>.outputs.x) |
inputs | workflow_dispatch / workflow_call parameters |
runner | runner info: runner.os, runner.temp |
| Function | What 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
| Variable | What to write to it |
|---|---|
$GITHUB_OUTPUT | name=value — a step output (steps.<id>.outputs.name) |
$GITHUB_ENV | NAME=value — an environment variable for the following steps |
$GITHUB_PATH | a directory added to PATH for the following steps |
$GITHUB_STEP_SUMMARY | Markdown 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
onin YAML 1.1 istrue. GitHub andactionlintread theonkey correctly, but YAML 1.1 parsers (e.g. PyYAML in Python scripts) turn it into the booleanTrue, anddata['on']raisesKeyError. In your own scripts look up the keyTrueor write"on":in quotes in the file.yes/no/offbehave the same way in YAML 1.1.actionlintwithout arguments looks for a git repository up the directory tree. Outside a repository it exits withno project was found— pass the file paths explicitly.- A workflow must live in
.github/workflows/and have a.ymlor.yamlextension, otherwise GitHub won't see it. - A step with both
usesandrunis an error. Split them into two steps. - Misspelled keys (
branchinstead ofbranches,stepinstead ofsteps,fetch_depthinstead offetch-depth) don't give a working workflow —actionlintcatches them. needs.<id>.outputsare available only if the job is listed inneedsand declaredoutputs. Otherwise the expression is empty, andactionlintwarns.- After a step fails, the following ones are skipped. For a step to always run (cleanup, report), use
if: always()orif: failure(). - Untrusted data in
runis an injection risk.${{ github.event.pull_request.title }}is substituted into the script as text. Pass such values viaenv:and use them as"$TITLE". scheduleruns 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