How to use this page
This is a lookup page. The reasons behind each key — and the traps — are on the skill pages, linked from each section. Search (Ctrl/⌘+K) finds any key on this page by its exact spelling.
A workflow with every top-level key
.github/workflows/tour.yml
name: Full syntax tour
run-name: ${{ github.workflow }} · ${{ github.event_name }} · ${{ github.ref_name }}
on:
push:
branches: [main]
workflow_dispatch:
inputs:
level:
type: choice
options: [quick, full]
default: quick
permissions:
contents: read
env:
TZ: UTC
defaults:
run:
shell: bash
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
build:
name: Build on ${{ matrix.os }}
runs-on: ${{ matrix.os }}
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
outputs:
version: ${{ steps.ver.outputs.version }}
env:
CI: 'true'
steps:
- uses: actions/checkout@v7
- id: ver
run: echo "version=$(cat VERSION)" >> "$GITHUB_OUTPUT"
- name: Full suite only when asked
if: inputs.level == 'full'
run: make test-all
timeout-minutes: 15
continue-on-error: true
working-directory: app
publish:
needs: build
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
environment:
name: registry
url: https://registry.example.com
permissions:
contents: read
packages: write
container:
image: node:24
services:
cache:
image: redis:8
steps:
- run: echo "Publishing ${{ needs.build.outputs.version }}"
shared:
needs: build
uses: ./.github/workflows/notify.yml
with:
version: ${{ needs.build.outputs.version }}
secrets: inheritWorkflow keys
| Key | Purpose |
|---|---|
name | Shown in the Actions tab and in badges; defaults to the file path |
run-name | Name of each run; can use github, inputs and vars |
on | Events, activity types and filters; no expressions allowed |
permissions | Default GITHUB_TOKEN scopes for every job |
env | Variables for every step of every job |
defaults.run | shell and working-directory for run steps |
concurrency | group, cancel-in-progress, queue (single or max) |
jobs | The jobs, keyed by an ID made of letters, digits, - and _, starting with a letter or _ |
Job keys
| Key | Purpose |
|---|---|
name | Display name (also the required-check name) |
needs | Jobs that must succeed first |
if | Condition; can read github, needs, vars, inputs |
runs-on | Labels, group or both |
permissions | Replaces the workflow's token scopes for this job |
environment | Name, or name and url |
concurrency | As at workflow level, per job |
outputs | Values for jobs that need this one |
env · defaults | Job-level variables and run defaults |
timeout-minutes | Default 360 |
strategy | matrix, fail-fast, max-parallel |
continue-on-error | Let the run pass if this job fails |
container | Run the steps in a container: image, credentials, env, ports, volumes, options |
services | Sidecar containers, with the same sub-keys |
uses · with · secrets | Call a reusable workflow instead of running steps |
steps | The steps |
Step keys
| Key | Purpose |
|---|---|
id | Needed to read the step's outputs, outcome and conclusion |
name | Display name |
if | Condition; adds success() && unless a status function is used |
uses | An action: owner/repo@ref, owner/repo/path@ref, ./path, docker://image |
with | Action inputs; args and entrypoint for Docker actions |
run | A script |
shell | bash, sh, pwsh, powershell, cmd, python, or a custom template with {0} |
env | Step variables — highest precedence |
working-directory | For run |
continue-on-error · timeout-minutes | Failure handling for the step |
Context availability
Which contexts each key can read. Anything not listed is not available there — the most common reason an expression "does nothing". Explained in Foundations.
| Key | Available contexts |
|---|---|
run-name, workflow concurrency | github, inputs, vars |
Workflow env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.strategy | github, needs, vars, inputs |
runs-on, job name, environment, timeout-minutes, continue-on-error, services, container | github, needs, strategy, matrix, vars, inputs |
Job env | The above, plus secrets |
environment.url | The above, plus job, runner, env, steps |
Step if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs — not secrets |
Step run, with, env, name, working-directory | Everything, including secrets |
Job outputs | Everything — but an output whose value contains a secret is redacted and not passed on |
on.workflow_call.outputs.<id>.value | github, jobs, vars, inputs |
hashFiles() works only in step-level keys; the status functions only in if.
Expression operators and functions
| Item | Meaning |
|---|---|
( ) [ ] . | Grouping, index (github['ref']), property |
! < <= > >= == != && || | Logic and comparison; string comparison ignores case |
contains(search, item) | Substring in a string, or item in an array |
startsWith(s, v) · endsWith(s, v) | Case-insensitive prefix and suffix tests |
format('{0}-{1}', a, b) | String templating; {{ escapes a brace |
join(array, sep) | Join with a separator (default ,) |
toJSON(v) · fromJSON(s) | Serialise · parse — fromJSON turns a JSON output into a matrix, a number or a boolean |
hashFiles(patterns…) | SHA-256 of the matching files, for cache keys |
a.*.b | Object filter: every b under every item of a |
Status check functions
| Function | True when | Typical use |
|---|---|---|
success() | No earlier failure or cancellation (the implicit default) | Normal steps |
failure() | An earlier step or needed job failed | Diagnostics, notifications |
cancelled() | The run was cancelled | Clean-up after a cancel |
always() | Always | Summaries, artifact uploads; prefer !cancelled() |
Workflow commands
| Command | Effect |
|---|---|
::group::title · ::endgroup:: | Fold lines in the log |
::error file=f,line=l,endLine=,col=,endColumn=,title=t::msg | Error annotation (also ::warning, ::notice) |
::debug::msg | Shown only with step debug logging |
::add-mask::value | Mask a value in all later log output |
::stop-commands::token · ::token:: | Pause and resume command processing |
::echo::on · ::echo::off | Echo commands into the log |
::set-output::save-state::set-env::add-path | Retired — use the environment files below |
Environment files
| File | Line format | Effect |
|---|---|---|
$GITHUB_ENV | NAME=value or NAME<<EOF … EOF | Variable for later steps of the job |
$GITHUB_OUTPUT | name=value (multiline form too) | Step output |
$GITHUB_PATH | A directory | Prepended to PATH for later steps |
$GITHUB_STATE | name=value | State for an action's post step, read as $STATE_name |
$GITHUB_STEP_SUMMARY | Markdown | Job summary (1 MiB per step) |
On Windows with PowerShell, append with "name=value" | Out-File -FilePath $env:GITHUB_OUTPUT -Append.
Default environment variables
| Variable | Value |
|---|---|
CI | Always true |
GITHUB_ACTIONS | true when running in Actions |
GITHUB_WORKFLOW · GITHUB_WORKFLOW_REF | Workflow name · owner/repo/.github/workflows/file.yml@ref |
GITHUB_RUN_ID · GITHUB_RUN_NUMBER · GITHUB_RUN_ATTEMPT | Unique run ID · per-workflow counter · re-run attempt |
GITHUB_JOB · GITHUB_ACTION | Job ID · current step or action ID |
GITHUB_EVENT_NAME · GITHUB_EVENT_PATH | The event · path of the payload JSON on the runner |
GITHUB_REPOSITORY · GITHUB_REPOSITORY_OWNER · GITHUB_REPOSITORY_ID | owner/repo · owner · numeric ID |
GITHUB_REF · GITHUB_REF_NAME · GITHUB_REF_TYPE | Full ref · short name · branch or tag |
GITHUB_HEAD_REF · GITHUB_BASE_REF | PR head and base branch (pull request events only) |
GITHUB_SHA | The commit the run uses |
GITHUB_ACTOR · GITHUB_TRIGGERING_ACTOR | Who started the original run · who started this attempt |
GITHUB_WORKSPACE | The checkout directory |
GITHUB_SERVER_URL · GITHUB_API_URL · GITHUB_GRAPHQL_URL | Host URLs (different on GHES and data residency) |
RUNNER_OS · RUNNER_ARCH · RUNNER_NAME | Linux, Windows, macOS · X64, ARM64 · runner name |
RUNNER_TEMP · RUNNER_TOOL_CACHE | Temp directory emptied after each job · toolcache |
RUNNER_DEBUG | 1 when debug logging is on |
Filter patterns
| Pattern | Matches |
|---|---|
* | Any characters except / |
** | Any characters, including / |
? · + | Zero or one · one or more of the preceding character |
[0-9] | One character from the set |
!pattern | Negates; later patterns override earlier ones |
'*.md' | Quote patterns that start with *, [ or ! — they mean something else in YAML |
Shells
shell | Command the runner uses |
|---|---|
| (unspecified, Linux/macOS) | bash -e {0}, or sh -e {0} if bash is missing |
bash | bash --noprofile --norc -eo pipefail {0} |
(unspecified, Windows) · pwsh | pwsh -command ". '{0}'" |
powershell · cmd | Windows PowerShell 5.1 · cmd /D /E:ON /V:OFF /S /C "CALL "{0}"" |
python · sh | python {0} · sh -e {0} |
pipefail only when you ask for bash
An unspecified shell on Linux is bash -e without pipefail, so
npm test | tee log.txt passes even when the tests fail. Set shell: bash (or
defaults.run.shell: bash) to get -o pipefail.
Action metadata
Top-level keys: name, description and runs (required), plus
author, inputs, outputs and branding. The runs block
depends on the type — details in Skill 3:
action.yml excerpt
runs:
using: node24
main: dist/index.js
pre: dist/setup.js
pre-if: runner.os == 'Linux'
post: dist/cleanup.js
post-if: always() action.yml excerpt
runs:
using: docker
image: docker://ghcr.io/octo-org/tool:3.2 # or: Dockerfile
pre-entrypoint: /setup.sh
entrypoint: /main.sh
post-entrypoint: /cleanup.sh
args:
- ${{ inputs.target }}
env:
MODE: strict action.yml excerpt
runs:
using: composite
steps:
- uses: actions/setup-node@v7
with:
node-version: ${{ inputs.node-version }}
- name: Build
id: build
shell: bash
working-directory: ${{ inputs.path }}
env:
TARGET: ${{ inputs.target }}
run: make "$TARGET"