Expressions and contexts

Expressions let a workflow compute values and conditions at run time: ${{ github.ref_name }}, if: failure(), ${{ fromJSON(needs.plan.outputs.matrix) }}. Diffinery implements the GitHub Actions expression language, with the same syntax, operators, functions and type rules, and fills in the same contexts. This page is the reference for all of it, including the default environment variables every step gets and every difference from GitHub.

#Syntax

An expression is written between ${{ and }}:

env:
  IMAGE: diffinery.com/acme/website:${{ github.sha }}
steps:
  - run: echo "Building ${{ github.ref_name }} for ${{ github.actor }}"

• In most values, each ${{ }} is replaced by its result converted to a string, and the text around it is kept.
• When a value is exactly one expression (for example matrix: ${{ fromJSON(needs.plan.outputs.matrix) }}), the result keeps its type: a list stays a list, a number stays a number.
• In if: conditions of jobs and steps, ${{ }} is optional: if: github.event_name == 'push' is the same as if: ${{ github.event_name == 'push' }}.
• }} inside a single-quoted string doesn't end the expression. To write a literal ${{, use ${{ '${{' }}.
• Expressions in on: are not evaluated.

Every expression in a file is checked for syntax when the file is parsed. A mistake fails the file with Invalid expression ${{ <expr> }}: <detail> (or Invalid expression: <detail> in an if: without ${{ }}), and an unclosed one with Unclosed expression: '${{' at offset <n> has no matching '}}'. Run diffinery workflow validate to catch these before you push.

Note: In an if: that mixes text and expressions, such as if: ${{ a }} && ${{ b }}, the result is a string, which is true unless it's empty. Write the whole condition as one expression instead: if: a && b. GitHub behaves the same way.

#Literals

#Operators

The or operator is ||. Precedence, from highest to lowest: property access and indexing, !, comparisons, equality, &&, ||. There are no arithmetic operators, as on GitHub.

&& and || return one of their operands, not a boolean: a && b is a when a is falsy and b otherwise; a || b is a when a is truthy and b otherwise. That gives you defaults: ${{ inputs.tag || 'latest' }}.

#Property access

• Property names are case-insensitive: github.EVENT_NAME reads github.event_name.
• Names may contain -: steps.build-app.outputs.path, matrix.node-version.
• Reading a property of something that doesn't have it gives null instead of an error, so github.event.pull_request.title is null on a push. An unknown context name is null too.
• Array indexes start at 0. An index out of range gives null.

#Object filters

.* collects a property from every item of an array or object and gives a list:

- run: echo "${{ toJSON(github.event.pull_request.labels.*.name) }}"
- if: contains(github.event.pull_request.labels.*.name, 'deploy')
  run: ./deploy.sh

#Types and conversion

Comparisons convert values the way GitHub does:

Truthiness: false, 0, -0, NaN, '' and null are falsy; everything else, including every array and object, is truthy.

When a result is inserted into text: null becomes '', booleans become true or false, whole numbers have no decimals, and arrays and objects become JSON (indented by 2 spaces).

#Functions

Function names are case-insensitive. Calling an unknown function fails with Unrecognized function '<name>', and a wrong number of arguments with Function '<name>' expects <n> argument(s) but got <m>.

Examples:

- run: echo "${{ format('{0}/{1}@{2}', github.repository_owner, github.event.repository.name, github.sha) }}"
- if: startsWith(github.ref, 'refs/tags/v')
  run: ./release.sh
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}

Runtime errors from functions fail the step or job that evaluates them:

#hashFiles

hashFiles takes one or more glob patterns relative to GITHUB_WORKSPACE (*, **, ?, [...], and !pattern to exclude). It hashes each matching file with SHA-256, then hashes those hashes together, and returns the hex digest. Files outside the workspace and .git directories are ignored. It returns '' when no file matches.

hashFiles only works in places evaluated on the runner, that is in steps, job env, container, services and outputs. Elsewhere (job if, runs-on, strategy, name) it returns ''.

#Status check functions

In a job's if:, the functions look at all of the job's ancestors: the jobs in its needs, the jobs those need, and so on up the chain, as on GitHub.

A matrix job's result combines its legs: any failed leg fails it, otherwise any cancelled leg cancels it, and it's skipped when every leg was skipped. A leg that failed with continue-on-error: true counts as a success. A reusable workflow call's result combines the jobs inside it the same way.

In a step's if::

When a job on a Diffinery-hosted runner is cancelled or hits its timeout-minutes, the step that is running stops, and then, as on GitHub, the remaining steps whose if: is true still run: if: always(), if: cancelled() and post steps such as the cache save with save-always. They have 5 minutes together. Use them to clean up what the job created, for example a test environment or a temporary repository. Cancelling the run a second time stops them at once. The job still ends as cancelled (or failed, after a timeout).

An if: that doesn't call any of these is treated as success() && (<condition>). So if: github.ref == 'refs/heads/main' is skipped after a failure, while if: always() && github.ref == 'refs/heads/main' still runs. Inside a composite action, the functions look at the action's own steps.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test
      - if: failure()
        run: echo "::error::Tests failed"
  notify:
    needs: test
    if: always()
    runs-on: ubuntu-latest
    steps:
      - run: echo "test finished with ${{ needs.test.result }}"

Because a job's default if: is success(), a skipped job skips every job that depends on it, directly or further down the chain. To run a job anyway, give it a status function, for example if: always() or if: ${{ !cancelled() && needs.build.result != 'failure' }}:

jobs:
  build:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - run: make
  test:
    needs: build            # skipped when build is skipped
    runs-on: ubuntu-latest
    steps:
      - run: make test
  report:
    needs: test
    if: ${{ !cancelled() }} # runs even when build and test were skipped
    runs-on: ubuntu-latest
    steps:
      - run: echo "test result was ${{ needs.test.result }}"

#Contexts

#Where each context is available

Some values are evaluated by Diffinery before a job starts, and the rest by the runner while the job runs, so not every context is available everywhere:

In places evaluated before the job starts, github.token is empty and github.workspace isn't set, and vars and secrets hold only repository (and organization) values: a job's environment variables and secrets are added when the job starts, so they're available in steps, jobs.<id>.env, container, services and outputs, but not in jobs.<id>.if, runs-on, name or environment itself.

#github

Information about the run and the event. Most properties are also environment variables (see Default environment variables).

GitHub properties Diffinery doesn't set include github.actor_id, github.repository_owner_id, github.workflow_sha, github.event_path (use the GITHUB_EVENT_PATH variable), github.env, github.path, github.output, github.state and github.step_summary (use the environment variables of the same names).

Note: github.run_number counts runs of all workflows in the repository, not each workflow separately as on GitHub. Because github.run_id is the run number, the two are always equal.

#env

Environment variables set in the workflow: the workflow's env, the job's env, the step's env and anything earlier steps wrote to $GITHUB_ENV. It doesn't include the default variables such as GITHUB_SHA; read those with github.* or in the shell.

env:
  STAGE: production
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - if: env.STAGE == 'production'
        run: echo "Deploying to $STAGE"

#vars

The repository's variables, set under Settings > Secrets and variables or with PUT /repos/{owner}/{repo}/actions/variables/{name}. In a job with environment:, the environment's variables are added once the job starts and win over repository variables with the same name. Names are stored in upper case, and lookups ignore case. An unset variable is ''. See Secrets and variables and Environments.

#secrets

Secret names are stored in upper case and lookups ignore case; an unset secret is ''. Inside a reusable workflow, secrets holds only what the caller passed (or everything with secrets: inherit), plus the two tokens. Secret values are masked in logs.

#matrix

The values of the current matrix combination, for example matrix.os and matrix.node. Empty for jobs without a matrix.

#strategy

#needs

For each job in the job's needs:

#steps

For each earlier step with an id in the same job (or the same composite action):

#runner

#job

#inputs

For workflow_dispatch runs: the dispatch inputs, typed (booleans are booleans, numbers are numbers). Inside a reusable workflow: the inputs the caller passed with with, plus declared defaults. For other events: empty.

#jobs

Only in on.workflow_call.outputs of a reusable workflow: jobs.<job_id>.result and jobs.<job_id>.outputs.<name> for the called workflow's jobs.

#Default environment variables

Every step gets these variables. Workflows can't override the GITHUB_* and RUNNER_* ones; setting them in env has no effect. Paths are those of hosted runners, where the repository acme/website is checked out at /workspace/website.

Set only in some cases:

Hosted runners also set LANG=C.UTF-8, LC_ALL=C.UTF-8, PIP_BREAK_SYSTEM_PACKAGES=1 (so pip install works with Ubuntu's Python) and COREPACK_ENABLE_DOWNLOAD_PROMPT=0.

GitHub variables that Diffinery doesn't set include GITHUB_ACTOR_ID, GITHUB_REPOSITORY_ID, GITHUB_REPOSITORY_OWNER_ID, GITHUB_WORKFLOW_SHA and GITHUB_REF_PROTECTED. GITHUB_TOKEN isn't an environment variable unless you set it, as on GitHub:

- run: gh api repos/${{ github.repository }}
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

#Differences from GitHub

• jobs.<id>.environment.url can't use step outputs.
• Job-level if: can also read the workflow-level env.
• hashFiles() returns '' outside steps and other runner-evaluated values.
• github.event.inputs keeps the types of dispatch inputs; on GitHub its values are strings.
• github.run_number counts runs across all workflows of the repository, and github.run_id is the same number.
• On a re-run, github.actor is whoever started the re-run (and github.triggering_actor matches it).
• github.ref_protected is always false, and secrets.DIFFINERY_TOKEN is an extra name for the job token.
• GITHUB_* and RUNNER_* defaults can't be overridden, but CI and DIFFINERY can.