References
Pass data between steps with {{references}}: run inputs, trigger data, earlier step outputs, loop items, factory facts and secrets, and when each is available.
On this page
References let a step use data from somewhere else in the run: the issue that started it, a field an earlier step produced, the current item in a loop, or a secret for a webhook. You write them in double braces, such as {{steps.plan.output.summary}}, in instructions, done criteria, gate criteria, messages, webhook bodies and decision conditions.
The editor autocompletes references when you type {{, and checks each one as you edit. A reference that can’t resolve is a problem that blocks Apply, so a run never reaches a step with a broken reference.
Syntax
A reference is a root followed by a dotted path, inside {{ }}. Spaces just inside the braces are allowed.
{{input.issue}}
{{ trigger.issue.url }}
{{steps.plan.output.summary}}
{{steps.ci.status}}
{{item.path}}
{{factory.branch}}
{{secrets.DEPLOY_HOOK_TOKEN}}Path segments start with a letter or underscore and may contain letters, digits, underscores and dashes, so step ids such as size-route work.
Roots
| Root | Example | Available when |
|---|---|---|
input | {{input.issue}} | The key exists in the workflow’s run inputs |
trigger | {{trigger.issue.title}} | One of the workflow’s triggers provides it |
steps | {{steps.plan.output.summary}} | The step runs before this one and declares that output |
item | {{item}}, {{item.index}} | Inside the body of a Repeat for each |
factory | {{factory.repos}} | Always |
secrets | {{secrets.STRIPE_TEST_KEY}} | Only in a Send to URL step’s headers and body, and the secret exists |
input
Run inputs are named values a run starts with, declared in the workflow’s Run inputs (inputs in YAML) with a key, type and description. A manual run asks for them; triggers fill them in where they can. The most common is issue, “The issue that started the run”.
inputs:
- { key: issue, type: markdown, description: The issue that started the run }
- { key: target_env, type: enum, values: [staging, production] }trigger
What a trigger exposes depends on its kind. If a workflow has several triggers, the union is available, and steps should handle a value being absent on runs started by a different trigger.
| Trigger | References |
|---|---|
| Issue label | {{trigger.issue.title}}, {{trigger.issue.url}}, {{trigger.issue.labels}} |
| Alert | {{trigger.alert.title}}, {{trigger.alert.url}}, {{trigger.alert.count}} (events in the last hour) |
| Mention | {{trigger.message}} (the message that mentioned it), {{trigger.author}} |
| Schedule, Recurring, Cron | {{trigger.time}} (when the run started) |
| Webhook | {{trigger.body}} (the whole payload), {{trigger.body.<key>}} for each top-level key in the sample payload |
| Event | {{trigger.event.type}}, {{trigger.event.payload}} |
For webhooks, paste a Sample payload on the trigger: “Its top-level keys show up as {{trigger.body.*}} in every step.” Deeper paths below a provided reference are allowed, such as {{trigger.body.deploy.sha}}. See Triggers.
steps
{{steps.<id>.output.<field>}} reads a declared output of an earlier step. {{steps.<id>.status}} reads whether it succeeded or failed and is always available for earlier steps.
“Earlier” means an ancestor: a step this one runs after, directly or through other steps. Parallel siblings are not ancestors, even if they usually finish first. If you need a sibling’s output, make this step run after it.
item
Inside the body of a Repeat for each, {{item}} is the current element of the list and {{item.index}} its position. Use {{item.<field>}} when items are objects, such as {{item.path}}.
factory
{{factory.name}} (this factory), {{factory.repos}} (repos it opens PRs in) and {{factory.branch}} (base branch). These are the only three keys.
secrets
{{secrets.NAME}} inserts a secret from Settings → API keys & secrets. Secrets are allowed only in a Send to URL step’s headers and body, are shown masked in the editor and in run transcripts, and are never given to a model. Everywhere else, agents get secrets as environment variables instead.
Validation messages
These are the exact problems the editor reports. Each names the reference and the step.
| Situation | Message |
|---|---|
| Unknown root | ”“{{issue.title}}” isn’t a known reference. Start with input, trigger, steps, item, factory or secrets.” |
| Step doesn’t exist | ”“{{steps.spec.output.doc}}” points at a step that doesn’t exist.” |
| Step doesn’t run before this one | ”“{{steps.spec.output.doc}}” isn’t available here: Spec doesn’t run before Implement.” |
| A step reading itself | ”“{{steps.plan.output.summary}}” isn’t available here: a step can’t read its own output.” |
| Wrong shape | ”“{{steps.plan.summary}}”: use steps.plan.output.<field> or steps.plan.status.” |
| Undeclared output | ”“{{steps.plan.output.risks}}”: Plan doesn’t declare an output called “risks”.” |
| Unknown input | ”“{{input.ticket}}”: there’s no run input called “ticket”.” |
| No trigger provides it | ”“{{trigger.alert.url}}”: none of this workflow’s triggers provide it.” |
| Item outside a loop | ”“{{item}}” only works inside a Repeat for each.” |
| Secret outside a webhook | ”“{{secrets.STRIPE_TEST_KEY}}”: secrets can only go in a webhook’s headers or body.” |
| Unknown secret | ”“{{secrets.STRIPE_KEY}}”: there’s no secret called “STRIPE_KEY”.” |
| Unknown factory key | ”“{{factory.owner}}”: use factory.name, factory.repos or factory.branch.” |
| Repeat over a non-list | ”“{{steps.scan.output.summary}}” is a markdown, not a list.” |
Where references are checked
| Step kind | Fields with references |
|---|---|
| All | Instructions, Done criteria, Gate criteria |
| Notify | Message |
| Send to URL | URL, header values, body (secrets allowed in headers and body) |
| Transform | Input |
| Repeat for each | Items |
| Decide | Output equals reference, Expression, outcome Instructions |
Example: a typed pipeline
A Transform turns an alert into fields, a Decide routes on one, and a Notify reports the result:
steps:
- id: classify
kind: transform
name: Classify the alert
owner: { kind: agent, agent: builder, model: sonnet-5.5 }
instructions: Extract the fields below from the input.
input: "{{trigger.alert.title}} ({{trigger.alert.count}} events/hr) {{trigger.alert.url}}"
outputs:
- { key: severity, type: enum, values: [low, medium, high], required: true }
- { key: service, type: text, required: true }
- id: fix
kind: agent
name: Reproduce and fix
owner: { kind: agent, agent: builder, model: opus-5.5 }
instructions: |
Reproduce the {{steps.classify.output.severity}} alert in {{steps.classify.output.service}},
then fix it with a regression test. Base branch: {{factory.branch}}.
outputs:
- { key: summary, type: markdown }
- id: tell
kind: notify
name: Post the result in Slack
owner: { kind: orchestrator }
instructions: Post the result to the channel.
channel: { type: slack, channel: "#payments-alerts" }
message: "{{steps.classify.output.service}}: {{steps.fix.output.summary}} ({{steps.fix.status}})"In a test run, the transcript shows references resolved, for example “Would post to #payments-alerts: “payments-api: Fixed retry clock…””.