${{ … }}. It resolves
at runtime against a typed scope (the three value authorities, task-scope
bindings, task records) and substitutes into the field. What’s inside
${{ }} is CEL (Common Expression Language), the
same expression language GitHub Actions and Kubernetes admission
policies use. Nika does not invent a DSL.
The parser keeps both forms of every templatable field: a literal value, or
a template island holding the unresolved expression. Templates are parsed by
the engine’s nika-tmpl crate and evaluated as CEL by nika-cel.
Two expression layers, locked by the spec: CEL
inside
${{ }} (conditions + value substitution) and jq inside
extract: bindings + the nika:jq builtin (extraction + transform).
There are no template filters: anything beyond a reference or a
boolean is a jq expression or a task. Engine-side, taint propagation
and typed scope lookup mature across admission rounds; the syntax
below is the ratified contract.Shape
${{ }} is ignored. Nested ${{ }} is rejected at
parse time.
The namespaces
Every binding resolves against one of named namespaces. The resolver refuses unknown top-level names at validation time, so${{ tsaks.foo }}
is caught before the run starts — and a value-namespace read outside the
closed family (${{ params.X }} and friends) refuses NIKA-VALUES-003.
The first three are the value authorities — the closed family every
workflow value is declared under, one role each, no alias.
with, tasks
and run are the runtime namespaces: legal in ${{ }}, never value
authorities. A run. name outside the closed set (${{ run.started }})
refuses NIKA-VAR-001.
${{ vars.X }}, ${{ env.X }} and ${{ config.X }} are dead reads
(NIKA-VALUES-001 / NIKA-VALUES-002 / NIKA-VALUES-003). Each old use
classifies into the authority its role commands — a typed parameter into
inputs:, a fixed value into const:, non-sensitive runtime configuration
into an inputs: entry with a default:, a governed store reference into
secrets:. Classification, never a bulk rename: the question is what the
value plays, not what it was spelled.
Task names are validated at parse time (snake_case, unique). A
binding that references a task not present in the file fails with a
miette diagnostic pointing at the exact byte range.
The reference boundary: where tasks.* may appear
The tasks namespace is boundary-only. A ${{ tasks.X.* }} reference
is legal in exactly five places: with: values (the binding IS the edge ·
${{ group.<name> }} is the plural, fan-in door: see
group) · after: keys (the entry
names the producer) · on_error.recover: (a fallback reads a settled
record) · an unwind task’s body (cleanup reads the producer it unwinds,
and only that one) · workflow outputs: (the run’s exports read the settled
world).
Everywhere else — verb fields (prompt: · command: · args: · …),
when:, for_each: — a tasks.* reference is refused at parse time
(NIKA-VAR-021) with a machine-applicable fix: hoist it into with:
and read the binding.
with · the
three value authorities inputs · const · secrets · the loop
locals): every cross-task dependency is visible at the boundary, named, and
typed by its edge role.
Typed resolution
Nika knows the expected type of every binding target. Ifinputs.count
is declared integer and you drop it into a field typed as a list,
validation fails before the run starts.
nika check: every deep output
reference is validated against its declared shape before anything runs.
Taint tracking
External data is tainted by default. The taint set is maintained by the analyzer and propagates through bindings:fetchoutput → tainted (HTTP body, third-party controlled).execstdout → tainted (subshell could have been influenced).infer/agentoutput → tainted (prompt injection vector).invokeoutput → tainted (MCP servers are third-party).inputs.*→ tainted (caller-supplied at launch — a deployment knob is an input with a default).- literals,
const.*,secrets.*→ trusted (the file owns them).
exec: task downstream of a nika:fetch (or nika:notify) task
is refused at check by the order law (NIKA-SEC-015), even through stdin:.
permits: { tools: ["nika:fetch", "nika:write"], fs: { write: ["./comment.txt"] } }:
inputs or a model’s answer, argv elements or stdin: are
the safe channels (each argv element is substituted on its own, with no
shell to break out of); the resolved program must still match
permits.exec (NIKA-SEC-004 at run otherwise). The
security model
describes the order law.
Taint is a property of data, not of a principal (T3:A design from
InferResponse.trust_level). Cross-link: ADR-014 (sealed kernel
traits), nika-error::trust::TrustLevel.
The expression language: CEL, one small subset
What’s inside${{ }} is the v0.1 CEL subset
(normative grammar):
There are no template filters (
\| upper, \| truncate, …). Anything
that transforms data is a jq expression, in an extract: binding or
through the nika:jq builtin. Two layers, one job each:
matches(), the list macros (all(), exists()) and arithmetic are not in
the subset (NIKA-VAR-005 names the functions that are): use nika:jq or
nika:assert for that work. In YAML, quote an expression that contains
: , such as a conditional, so the YAML parser keeps it whole:
prompt: "${{ has(inputs.style) ? inputs.style : 'be concise' }}".
Multi-line
YAML block scalars compose cleanly with bindings (the pull-request fields crossed the boundary inwith:; the prompt reads the bindings):
Null handling
Defaults live in declarations, not in expressions. Which declaration depends on who owns the value:inputs.optional_field is required and the caller supplies nothing,
the run is refused before it starts: a miette diagnostic points at the
declaration site and the usage site.
What bindings are not
- ❌ Not a scripting language. No statements or loops inside
${{ }}; the only conditional is the? :expression. - ❌ Not arbitrary JavaScript / Python eval. No dynamic code.
- ❌ Not Jinja2 / Liquid in full:
forandifblocks are not supported inside expressions. - ✅ Scope lookup + CEL evaluation + type check + taint propagation.
for_each:, when:, the with: /
after: edges) lives on the task envelope, not inside bindings.
This is deliberate: the DAG is a static artifact, inspectable by the
analyzer and renderable by any graph surface — nika inspect <file> --format mermaid|dot|json; bindings are local decorations.
Related ADRs
- ADR-010: miette as the L4 diagnostic presentation layer. Every binding error points at the exact byte range in the source file.
- ADR-014: sealed kernel traits. The resolver runs at L3 and never crosses into arbitrary user-provided evaluator code.
- ADR-113: the nine-key envelope; the workflow’s identity moves onto
nika:.${{ }}bindings resolve against the same scope shape in every document.
Read next
Events
What gets emitted, when.
Workflows
The envelope that holds the
tasks: bindings operate on.Verbs
Each verb’s taint classification and sanitizer expectations.
YAML reference
Full binding grammar and CEL subset.