Shipfox

Expressions (CEL)

Look up the syntax, operators, and functions available inside a Shipfox expression.

Shipfox expressions use CEL. A workflow writes them in two forms.

A template puts a value into text with ${{ }}. A predicate gives a true or false result that controls a trigger, job, step, or gate.

For the data an expression can read, see Contexts.

Syntax

Write an expression between ${{ and }}:

run: echo "Building ${{ trigger.event }}"
FormExampleResult
Property accessevent.refThe ref property of event
Index accessvars["API_URL"]A property whose name is not an identifier
List indexexecution.events[0].dataThe first element of a list
Escape$${{The literal text ${{

A predicate field takes the expression on its own. An if field takes exactly one ${{ }} and nothing else:

if: ${{ trigger.event == "push" }}

Shipfox checks two fields before it runs a step or a job:

  1. run_after looks at earlier failures. The default value is success. With this value, Shipfox skips the step or job after a failure.
  2. if is checked only when run_after lets the step or job run.

An if cannot make a step or job run after a failure. Use run_after for that:

To run a step or jobSet
Only after a failurerun_after: failure
After a success and after a failurerun_after: always

See When a step or job runs.

Run identifiers

The run context has a UUID id and a sequential number. The UUID identifies the run in API and client routes. The number is scoped to the workflow definition and is available for labels, predicates, and display text. It is not resolved as a route address.

execution_name: 'Deploy #${{ run.number }}'

Types

TypeWritten as
string"refs/heads/main"
int42
double1.5
booltrue
list["main", "release"]
map{"env": "prod"}
dynA value whose shape is not known when the expression is checked
timestamptimestamp("2026-01-01T00:00:00Z")

Operators

OperatorExampleResult
==, !=trigger.event == "push"Compares compatible values; dyn is checked at evaluation time
<, <=, >, >=run.created_at > timestamp("2026-01-01T00:00:00Z")Orders numbers, strings, and timestamps
&&, ||, !job.key == "deploy" && !step.is_retryCombines boolean values
in"prod" in inputs.environmentsTrue when a list contains the value
in"API_URL" in varsTrue when a map contains the key
+"v" + inputs.versionAdds numbers, joins strings, joins lists
-, *, /, %executions.size() % 2 == 0Arithmetic on numbers
? :run.number == 1 ? "first" : "rerun"The middle value when true, the last when false
( )(a || b) && cGroups an expression against precedence

Static checking rejects incompatible known types rather than treating them as a false result. Dynamic values are checked when the expression runs, and numeric comparisons support both int and double. A predicate that errors never passes. When the if of a job or step errors, the job or step fails and the message names the cause. It is not skipped.

Functions and macros

CallExampleResult
list.size(), string.size()executions.size() > 1Number of elements or characters
list.first()execution.events.first().dataThe first element of a list
list.last()execution.events.last().dataThe final element of a list
list.all(item, predicate)executions.all(e, e.status == "succeeded")True when every element matches
list.exists(item, predicate)execution.events.exists(e, e.event == "push")True when at least one element matches
list.exists_one(item, predicate)needs.exists_one(j, j.status == "failed")True when exactly one element matches
list.filter(item, predicate)executions.filter(e, e.status == "failed")The elements that match
list.map(item, expression)needs.map(j, j.key)The expression applied to each element
string.contains(part)event.ref.contains("release")True when the string contains part
string.startsWith(part), string.endsWith(part)event.ref.startsWith("refs/heads/")Prefix and suffix tests
string.matches(pattern)event.ref.matches("^refs/tags/v[0-9]+$")True when the string matches a regular expression
string.split(separator)event.ref.split("/")[2]The parts between each separator
string.lowerAscii(), string.upperAscii()event.ref.lowerAscii()The string in one case
has(field)has(event.pull_request)True when the field is present
string(value), int(value), double(value)"run-" + string(run.number)The value converted to that type
timestamp(string)timestamp("2026-01-01T00:00:00Z")A timestamp from an RFC 3339 string
range(start, stop, step)range(1, 3, 1)An inclusive list of integers
toJson(value)toJson(event.pull_request.labels)The value serialized as compact JSON text
fromJson(string)fromJson(event.payload)The JSON text parsed into a dynamic CEL value
hashFiles(pattern, ...)hashFiles('package-lock.json')A hash of the files that match. See Hash files

list.first() and list.last() keep the element's type. Calling either method on an empty list causes an evaluation error. A job or step if that hits one fails the job or step with the reason condition_errored, and the steps that run by default after it are skipped. Guard a value that may be missing with has(), as in has(steps.build.outputs.sha) && steps.build.outputs.sha != "".

range() accepts a positive step and can materialize at most 1,000 values and 1,000,000 context-byte fan-out units in one evaluation. toJson() can produce at most 1,000,000 UTF-8 bytes in one evaluation. fromJson() expects a valid JSON string and converts safe integer numbers to CEL integers. toJson() writes integers outside the range JSON numbers represent exactly as quoted strings.

Lookups through an open map, schema-less tool output, or an unknown JSON Schema are dyn. They can be used with field access, methods, and comparisons, but a runtime failure still makes the surrounding predicate fail.

The CEL language definition documents the full standard library.

Hash files

hashFiles() gives a hash of files. Use it in a cache key:

key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

The hash has 32 characters, 0-9 and a-f. It changes when the path or the content of a file changes.

Choose the files

Give the paths of the files to hash. Write each path from the root of your repository, or from the working_directory of the step when it has one. Put each path in quotes, and separate paths with commas. Give at most 16 paths:

# One file
key: deps-${{ hashFiles('package-lock.json') }}
# Two files
key: deps-${{ hashFiles('package-lock.json', 'pnpm-workspace.yaml') }}
# All package.json files one folder under packages
key: deps-${{ hashFiles('packages/*/package.json') }}

A path can contain wildcards to match many files:

WildcardMatchesExample
*Any characters in one folder or file name*.lock
**Any number of folders**/package-lock.json
?One characterv?.txt
[...]One of the characters in the bracketsv[12].txt
{a,b}One of the comma-separated words{yarn,pnpm}.lock

Rules:

  • A path must name files in that folder. Do not start a path with ~ or /. Do not use ...
  • Put hashFiles() alone in its ${{ }}. Write npm-${{ hashFiles('x') }}. Do not write ${{ 'npm-' + hashFiles('x') }}.

Where to use it

Use hashFiles() in run, in env values, and in the with of an action. Other fields, such as if, cannot use it.

The hash includes the files that earlier steps of the job created or changed.

Errors

The step fails when:

  • No file matches the paths. GitHub Actions does not fail in this case.
  • The paths match more than 10,000 files.
  • The files are larger than 1 GiB in total.
  • Hashing takes more than 60 seconds.

If the step fails because of a limit, use a more specific path. For example, use package-lock.json, not **/package-lock.json.

Was this page helpful?
Edit this page on GitHub

On this page