Skip to main content
A binding is a template expression wrapped in ${{ … }}. 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

Four examples, each a valid template:
Whitespace inside ${{ }} 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.
The task body is a pure function of its declared inputs (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. If inputs.count is declared integer and you drop it into a field typed as a list, validation fails before the run starts.
Type-checking is the analyzer’s job, live in 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:
  • fetch output → tainted (HTTP body, third-party controlled).
  • exec stdout → tainted (subshell could have been influenced).
  • infer / agent output → tainted (prompt injection vector).
  • invoke output → 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).
Integrity is orthogonal to confidentiality: a secret is trusted (the author put it there) and confidential (it must not leak). One untrusted operand taints the whole interpolation. Content fetched from the network never reaches a shell, whatever the channel: an 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:.
Fix: do the work in a builtin, never a shell. Under permits: { tools: ["nika:fetch", "nika:write"], fs: { write: ["./comment.txt"] } }:
For a caller’s 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 in with:; the prompt reads the bindings):
The parser preserves indentation and line breaks: the prompt reaches the provider exactly as you typed it, minus the leading YAML block indentation.

Null handling

Defaults live in declarations, not in expressions. Which declaration depends on who owns the value:
If 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: for and if blocks are not supported inside expressions.
  • ✅ Scope lookup + CEL evaluation + type check + taint propagation.
Workflow-level control flow (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.
  • 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.

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.