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

RootExampleAvailable 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.

TriggerReferences
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.

SituationMessage
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 kindFields with references
AllInstructions, Done criteria, Gate criteria
NotifyMessage
Send to URLURL, header values, body (secrets allowed in headers and body)
TransformInput
Repeat for eachItems
DecideOutput 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…””.

    Type to search the docs, help center and blog.