codician/diffinerypublic

---

#title: Expressions and contexts description: The ${{ }} expression language in Diffinery workflows: operators, functions, every context property Diffinery sets, and the default environment variables.

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::

In a step's if::

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 }}"

Important: Two differences from GitHub at the job level. On GitHub, when a job is skipped, every job that needs it is skipped too; on Diffinery a skipped job counts as a success, so the jobs that need it run. And failure() only looks at the jobs listed in the job's own needs, not at the jobs those depend on. If a job must not run after an earlier failure further up the chain, list that job in needs or check its result, for example if: needs.build.result == 'success'.

#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, and github.run_id is a hexadecimal string, not a number.

#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, GITHUB_REF_PROTECTED, ImageOS and ImageVersion. 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

• A skipped job counts as a success for the jobs that need it, so they run; on GitHub they're skipped. failure() in a job's if: only looks at its direct needs.
• runs-on can't use the matrix context.
• jobs.<id>.environment can't use the needs or strategy contexts, and its 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_id is a hexadecimal string, and github.run_number counts runs across all workflows of the repository.
• 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.