# Workflow contexts (https://www.shipfox.io/docs/reference/contexts)

Description: Look up every context a workflow can read, the properties it holds, and the fields that can read it.

A **context** is a group of run data that an expression can read. See
[Expressions](https://www.shipfox.io/docs/reference/expressions) for the syntax.

## Available contexts [#available-contexts]

| Context | Holds |
|---|---|
| `workflow` | The workflow definition this run came from. |
| `run` | The current run. |
| `trigger` | The trigger that started the run. |
| `event` | The raw payload of the event that started the run. |
| `inputs` | Values the trigger `with` block passed into the run. |
| `job` | The current job. |
| `executions` | Every execution of the current job. |
| `execution` | The current execution of the job. |
| `jobs` | Upstream jobs, keyed by job key. |
| `needs` | The jobs this job declares in `needs`. |
| `steps` | Earlier steps of the current job, keyed by step key. |
| `step` | The current step. Its properties depend on the field that reads it. |
| `vars` | Workspace and project variables. |
| `secrets` | Workspace and project secrets. |
| `result` | The result returned by the current tool step. |

## Context availability [#context-availability]

Different contexts exist at different points in a run, so each field can read
only some of them. A trigger `filter` runs before Shipfox creates a run, so it
reads only `event` and `trigger`. A gate runs after its step reports, so it
reads `step` and `vars`.

| Workflow key | Available contexts |
|---|---|
| `triggers.<trigger_id>.filter` | `event`, `trigger` |
| `jobs.<job_id>.listening.on[*].filter` | `event`, `workflow`, `run`, `trigger`, `inputs`, `vars`, `job`, `jobs` |
| `jobs.<job_id>.listening.until[*].filter` | `event`, `workflow`, `run`, `trigger`, `inputs`, `vars`, `job`, `jobs` |
| `jobs.<job_id>.if` | `workflow`, `run`, `trigger`, `event`, `inputs`, `vars`, `jobs`, `needs` |
| `jobs.<job_id>.steps[*].if` | `vars`, `jobs`, `execution`, `step`, `steps` |
| `jobs.<job_id>.steps[*].gate.success` | `step`, `vars` |
| `jobs.<job_id>.success` | `executions`, `jobs`, `vars` |
| `jobs.<job_id>.steps[*].run` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars`, `secrets` |
| `env.<name>` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars`, `secrets` |
| `jobs.<job_id>.steps[*].prompt` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].model` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].provider` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].thinking` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].session` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.runner` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.outputs.<name>` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `run_name` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.execution_name` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].name` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].working_directory` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].checkout.project` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].checkout.connection` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].checkout.repository` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].checkout.ref` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].checkout.path` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].gate.on_failure.feedback` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].with` | `workflow`, `run`, `trigger`, `event`, `inputs`, `job`, `executions`, `execution`, `jobs`, `needs`, `steps`, `step`, `vars` |
| `jobs.<job_id>.steps[*].outputs.<name>` | `result`, `vars` |

A field cannot read the value it sets. For example, `run_name` cannot read
`run.name`.

Workflow sync fails when a field uses an unavailable context. The error
identifies the context. Shipfox does not substitute an empty value. See [Correct
a context that is not
available](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/workflow-sync#correct-a-context-that-is-not-available)
for recovery steps.

## Context properties [#context-properties]

### `workflow`

The workflow definition this run came from.

| Property | Type | Description |
|---|---|---|
| `workflow.id` | `string` | Identifier of the workflow definition. |
| `workflow.name` | `string` | Workflow `name` from the definition. |

### `run`

The current run.

| Property | Type | Description |
|---|---|---|
| `run.id` | `string` | Identifier of the run. |
| `run.number` | `int` | Sequential run number within the workflow definition. |
| `run.attempt` | `int` | Attempt number of the current run, starting at one. |
| `run.name` | `string` | Resolved run name, or the workflow name when `run_name` is not set. |
| `run.project_id` | `string` | Identifier of the project that owns the run. |
| `run.workspace_id` | `string` | Identifier of the workspace that owns the run. |
| `run.created_at` | `timestamp` | Time the run was created. |

### `trigger`

The trigger that started the run.

| Property | Type | Description |
|---|---|---|
| `trigger.source` | `string` | Integration connection slug, or `manual` or `cron`. |
| `trigger.event` | `string` | Shipfox event name that matched the trigger. |
| `trigger.project` | `object` | Shipfox project resolved from the event repository. Null when there is none. |
| `trigger.project.id` | `string` | Identifier of the resolved project. |
| `trigger.repository` | `string` | Repository the event came from, as `owner/name`. Null when there is none. |
| `trigger.ref` | `string` | Git ref the event carried. Null when there is none. |
| `trigger.commit` | `string` | Commit SHA the event carried. Null when there is none. |

### `event`

The raw payload of the event that started the run.

The provider owns this payload, so it has no fixed shape. Each provider page under [Integrations](https://www.shipfox.io/docs/integrations) lists the events Shipfox delivers and links the payload each one carries.

### `inputs`

Values the trigger `with` block passed into the run.

The keys are the ones the trigger declares. See [trigger fields](https://www.shipfox.io/docs/reference/workflow-schema#trigger-fields).

### `job`

The current job.

| Property | Type | Description |
|---|---|---|
| `job.key` | `string` | Key of the job in the `jobs` map. |
| `job.name` | `string` | Job `name`, or the job key when no name is set. |

### `executions`

Every execution of the current job.

| Property | Type | Description |
|---|---|---|
| `executions[*].index` | `int` | Position of the execution in its job, starting at zero. |
| `executions[*].name` | `string` | Resolved execution name, or the job name when `execution_name` is not set. |
| `executions[*].status` | `string` | Final status of the execution. |
| `executions[*].started_at` | `timestamp` | Time the execution started. |
| `executions[*].finished_at` | `timestamp` | Time the execution finished. |
| `executions[*].events` | `list<object>` | Listener events in the batch that started this execution. Empty for a standard job. |
| `executions[*].events[*].event_ref` | `string` | Stable identifier for the listener event. |
| `executions[*].events[*].source` | `string` | Integration connection slug that delivered the event. |
| `executions[*].events[*].event` | `string` | Shipfox event name. |
| `executions[*].events[*].delivery_id` | `string` | Identifier of the provider delivery. |
| `executions[*].events[*].received_at` | `timestamp` | Time Shipfox received the event. |
| `executions[*].events[*].project` | `object` | Shipfox project resolved from the event repository. Null when there is none. |
| `executions[*].events[*].project.id` | `string` | Identifier of the resolved project. |
| `executions[*].events[*].repository` | `string` | Repository the event came from, as `owner/name`. Null when there is none. |
| `executions[*].events[*].ref` | `string` | Git ref the event carried. Null when there is none. |
| `executions[*].events[*].commit` | `string` | Commit SHA the event carried. Null when there is none. |
| `executions[*].events[*].disposition` | `string` | Whether the listener event fired an execution or resolved the listener. |
| `executions[*].events[*].outcome` | `string` | Processing outcome recorded for the listener event. |
| `executions[*].events[*].outcome_reason` | `string` | Reason recorded when the listener event was rejected or abandoned. |
| `executions[*].events[*].stored_payload_bytes` | `int` | Bytes stored for the event payload. |
| `executions[*].events[*].normalized_event_bytes` | `int` | Bytes in the normalized event sent to execution. |
| `executions[*].events[*].data` | `map` | Raw event payload. The provider owns its shape. |
| `executions[*].outputs` | `map` | Outputs the execution produced, keyed by output name. |

### `execution`

The current execution of the job.

| Property | Type | Description |
|---|---|---|
| `execution.index` | `int` | Position of the execution in its job, starting at zero. |
| `execution.name` | `string` | Resolved execution name, or the job name when `execution_name` is not set. |
| `execution.status` | `string` | Final status of the execution. |
| `execution.started_at` | `timestamp` | Time the execution started. |
| `execution.finished_at` | `timestamp` | Time the execution finished. |
| `execution.events` | `list<object>` | Listener events in the batch that started this execution. Empty for a standard job. |
| `execution.events[*].event_ref` | `string` | Stable identifier for the listener event. |
| `execution.events[*].source` | `string` | Integration connection slug that delivered the event. |
| `execution.events[*].event` | `string` | Shipfox event name. |
| `execution.events[*].delivery_id` | `string` | Identifier of the provider delivery. |
| `execution.events[*].received_at` | `timestamp` | Time Shipfox received the event. |
| `execution.events[*].project` | `object` | Shipfox project resolved from the event repository. Null when there is none. |
| `execution.events[*].project.id` | `string` | Identifier of the resolved project. |
| `execution.events[*].repository` | `string` | Repository the event came from, as `owner/name`. Null when there is none. |
| `execution.events[*].ref` | `string` | Git ref the event carried. Null when there is none. |
| `execution.events[*].commit` | `string` | Commit SHA the event carried. Null when there is none. |
| `execution.events[*].disposition` | `string` | Whether the listener event fired an execution or resolved the listener. |
| `execution.events[*].outcome` | `string` | Processing outcome recorded for the listener event. |
| `execution.events[*].outcome_reason` | `string` | Reason recorded when the listener event was rejected or abandoned. |
| `execution.events[*].stored_payload_bytes` | `int` | Bytes stored for the event payload. |
| `execution.events[*].normalized_event_bytes` | `int` | Bytes in the normalized event sent to execution. |
| `execution.events[*].data` | `map` | Raw event payload. The provider owns its shape. |
| `execution.outputs` | `map` | Outputs the execution produced, keyed by output name. |
| `execution.failed` | `bool` | Whether an earlier step in this execution failed. |

### `jobs`

Upstream jobs, keyed by job key.

The keys are the job keys the workflow declares.

| Property | Type | Description |
|---|---|---|
| `jobs.<job_key>.key` | `string` | Key of the job in the `jobs` map. |
| `jobs.<job_key>.status` | `string` | Final status of the job. |
| `jobs.<job_key>.outputs` | `map` | Declared job outputs, keyed by output name. |
| `jobs.<job_key>.executions` | `list<object>` | Executions of the job, each with the properties of the `execution` context. A standard job has one. |

### `needs`

The jobs this job declares in `needs`.

| Property | Type | Description |
|---|---|---|
| `needs[*].key` | `string` | Key of the job in the `jobs` map. |
| `needs[*].status` | `string` | Final status of the job. |
| `needs[*].outputs` | `map` | Declared job outputs, keyed by output name. |
| `needs[*].executions` | `list<object>` | Executions of the job, each with the properties of the `execution` context. A standard job has one. |

### `steps`

Earlier steps of the current job, keyed by step key.

The keys are the step keys the workflow declares.

| Property | Type | Description |
|---|---|---|
| `steps.<step_key>.status` | `string` | Final status of the step. |
| `steps.<step_key>.exit_code` | `int` | Exit code of the most recent finished attempt. |
| `steps.<step_key>.outputs` | `map` | Declared step outputs of the most recent finished attempt. |
| `steps.<step_key>.response` | `string` | Final agent response. Absent on a run step. |
| `steps.<step_key>.gate` | `object` | Gate result of the most recent finished attempt. Absent when the step has no gate. |
| `steps.<step_key>.gate.passed` | `bool` | Whether the gate expression passed. |
| `steps.<step_key>.gate.source` | `string` | Gate expression that produced the result. |
| `steps.<step_key>.gate.reason` | `string` | Why Shipfox could not check the gate. |
| `steps.<step_key>.gate.exit_code` | `int` | Exit code the gate read. |
| `steps.<step_key>.attempts` | `list<object>` | Every finished attempt of the step, oldest first. |
| `steps.<step_key>.attempts[*].status` | `string` | Final status of the attempt. |
| `steps.<step_key>.attempts[*].exit_code` | `int` | Exit code the attempt reported. |
| `steps.<step_key>.attempts[*].outputs` | `map` | Declared outputs the attempt reported. |
| `steps.<step_key>.attempts[*].response` | `string` | Final agent response of the attempt. Absent on a run step. |
| `steps.<step_key>.attempts[*].gate` | `object` | Gate result of the attempt. Absent when the step has no gate. |
| `steps.<step_key>.attempts[*].gate.passed` | `bool` | Whether the gate expression passed. |
| `steps.<step_key>.attempts[*].gate.source` | `string` | Gate expression that produced the result. |
| `steps.<step_key>.attempts[*].gate.reason` | `string` | Why Shipfox could not check the gate. |
| `steps.<step_key>.attempts[*].gate.exit_code` | `int` | Exit code the gate read. |

### `step`

The current step. Its properties depend on the field that reads it.

| Property | Type | Description |
|---|---|---|
| `step.attempt` | `int` | Attempt number of the step, starting at one. Not readable in `gate.success`. |
| `step.is_retry` | `bool` | Whether the current step ran before. This does not identify which gate failed. Not readable in `gate.success`. |
| `step.restart` | `object` | Set when a gate failure causes Shipfox to run this step again. It remains set for later steps after the gate passes. A later gate restart replaces it. Not readable in `gate.success`. |
| `step.restart.from` | `object` | The gate step whose failure caused the restart. It includes the properties of a `steps` entry and its optional authored `key`. The key identifies the failed gate, not the restart target. Not readable in `gate.success`. |
| `step.restart.feedback` | `string` | Feedback the restarting gate produced. Not readable in `gate.success`. |
| `step.exit_code` | `int` | Exit code the step reported. Readable in `gate.success` only. |
| `step.status` | `string` | Status the step reported. Readable in `gate.success` only. |
| `step.outputs` | `map` | Outputs the step reported. Readable in `gate.success` only. |

### `vars`

Workspace and project variables.

The keys are the variable names the workspace defines. See [Secrets and variables](https://www.shipfox.io/docs/reference/secrets-variables).

### `secrets`

Workspace and project secrets.

The keys are the secret names the workspace defines. See [Secrets and variables](https://www.shipfox.io/docs/reference/secrets-variables).

### `result`

The result returned by the current tool step.

The selected tool catalog defines this value. It is readable only while mapping tool outputs at step reporting.

## Related pages [#related-pages]

### [Expressions](https://www.shipfox.io/docs/reference/expressions)

The syntax, operators, and functions available inside an expression.

### [Workflow schema](https://www.shipfox.io/docs/reference/workflow-schema)

The fields that carry these expressions.

### [Secrets and variables](https://www.shipfox.io/docs/reference/secrets-variables)

How `vars` and `secrets` are stored, scoped, and bound.