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 }}"| Form | Example | Result |
|---|---|---|
| Property access | event.ref | The ref property of event |
| Index access | vars["API_URL"] | A property whose name is not an identifier |
| List index | execution.events[0].data | The 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:
run_afterlooks at earlier failures. The default value issuccess. With this value, Shipfox skips the step or job after a failure.ifis checked only whenrun_afterlets 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 job | Set |
|---|---|
| Only after a failure | run_after: failure |
| After a success and after a failure | run_after: always |
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
| Type | Written as |
|---|---|
string | "refs/heads/main" |
int | 42 |
double | 1.5 |
bool | true |
list | ["main", "release"] |
map | {"env": "prod"} |
dyn | A value whose shape is not known when the expression is checked |
timestamp | timestamp("2026-01-01T00:00:00Z") |
Operators
| Operator | Example | Result |
|---|---|---|
==, != | 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_retry | Combines boolean values |
in | "prod" in inputs.environments | True when a list contains the value |
in | "API_URL" in vars | True when a map contains the key |
+ | "v" + inputs.version | Adds numbers, joins strings, joins lists |
-, *, /, % | executions.size() % 2 == 0 | Arithmetic on numbers |
? : | run.number == 1 ? "first" : "rerun" | The middle value when true, the last when false |
( ) | (a || b) && c | Groups 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
| Call | Example | Result |
|---|---|---|
list.size(), string.size() | executions.size() > 1 | Number of elements or characters |
list.first() | execution.events.first().data | The first element of a list |
list.last() | execution.events.last().data | The 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:
| Wildcard | Matches | Example |
|---|---|---|
* | Any characters in one folder or file name | *.lock |
** | Any number of folders | **/package-lock.json |
? | One character | v?.txt |
[...] | One of the characters in the brackets | v[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${{ }}. Writenpm-${{ 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.
Related pages
Contexts
Every context, its properties, and the fields that can read it.
Workflow schema
The fields that carry these expressions.
Context and templating
Why templates and predicates are separate, and how commands receive values.