GitHub Actions/Workflow Syntax/Expressions, contexts and special files

ReferenceUpdated 3 weeks ago

Expressions, contexts and special files

How to read data inside workflows with ${{ }}: github, env, vars, secrets, steps, needs and inputs contexts, status functions, and the GITHUB_OUTPUT / GITHUB_ENV / GITHUB_STEP_SUMMARY files.

#github-actions #expressions #contexts

Contexts you use daily

Expression	Value
`github.sha`	Full commit SHA
`github.ref`	`refs/heads/main`, `refs/tags/v1.4.0`, `refs/pull/12/merge`
`github.ref_name`	`main` or `v1.4.0` (short)
`github.event_name`	`push`, `pull_request`, `workflow_dispatch`...
`github.repository`	`owner/repo`
`github.actor`	User who triggered the run
`github.run_number`	Increasing run counter (good for build numbers)
`env.NAME`	Workflow/job/step env variable
`vars.NAME`	Configuration variable (not secret)
`secrets.NAME`	Encrypted secret (masked in logs)
`inputs.NAME`	workflow_dispatch / workflow_call input
`steps.<id>.outputs.x`	Output of an earlier step
`needs.<job>.outputs.x`	Output of a required job
`matrix.x`	Current matrix value
`runner.os`	`Linux`, `Windows`, `macOS`

Conditions and functions

if: examples

YAML

1if: github.event_name == 'push' && github.ref == 'refs/heads/main'

2if: startsWith(github.ref, 'refs/tags/v')

3if: contains(github.event.head_commit.message, '[skip deploy]') == false

4if: success() # default: all previous steps passed

5if: failure() # a previous step failed

6if: always() # run even after failure/cancel (cleanup, reports)

7if: cancelled()

9# other functions

10key: deps-${{ hashFiles('**/package-lock.json') }}

11image: ${{ format('ghcr.io/{0}', github.repository) }}

12json: ${{ toJSON(github.event) }}

Special files

Write to these files from a run: step. Never use the removed ::set-output syntax.

GITHUB_OUTPUT, GITHUB_ENV, GITHUB_STEP_SUMMARY, GITHUB_PATH

SHELL

1# output for later steps: ${{ steps.<id>.outputs.tag }}

2echo "tag=v1.4.0" >> "$GITHUB_OUTPUT"

4# env var for ALL later steps in this job: $APP_VERSION

5echo "APP_VERSION=1.4.0" >> "$GITHUB_ENV"

7# add a directory to PATH for later steps

8echo "$HOME/.local/bin" >> "$GITHUB_PATH"

10# markdown shown on the run summary page

11echo "### Deployed v1.4.0 :rocket:" >> "$GITHUB_STEP_SUMMARY"

13# mask a dynamic value in logs

14echo "::add-mask::$TOKEN"

16# annotations

17echo "::warning file=app.js,line=3::Deprecated API"

18echo "::error::Tests failed"

Injection safety

Never put untrusted input (PR titles, branch names, issue bodies) directly into run: with ${{ }}. Pass it through env first: env: { TITLE: ${{ github.event.pull_request.title }} } then use "$TITLE" in the script.