> ## Documentation Index
> Fetch the complete documentation index at: https://www.shipfox.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Shipfox Glossary: Key Terms and Concepts

> Definitions for every Shipfox term: workspace, project, workflow, run, job, step, trigger, runner, gate, CEL, filter, key, and more. Quick reference.

This glossary defines the core terms used in Shipfox documentation and in the product UI. When a concept is introduced elsewhere in the docs, it links back here.

<AccordionGroup>
  <Accordion title="Agent step">
    A workflow step that invokes an AI model. Defined with `prompt` (required), plus optional `model`, `thinking`, and `provider` fields. The model reads the repository context and executes the prompt. Agent steps cannot carry `env` — use a run step for environment-dependent shell work. See the [Step Types reference](/reference/step-types#agent-step).
  </Accordion>

  <Accordion title="CEL">
    Common Expression Language — a lightweight expression language used in Shipfox for trigger filters (`filter`) and step success conditions (`success_if`). CEL expressions are type-safe, side-effect-free, and sandboxed. In `success_if`, the variable `exit_code` (integer) is available. In `filter`, the variable `event` carries the event payload. See the [CEL specification](https://cel.dev) for syntax details.
  </Accordion>

  <Accordion title="Filter">
    An optional CEL expression on a trigger that is intended to narrow which events fire the workflow. For example, `event.ref == "refs/heads/main"` on a GitHub push trigger would restrict to pushes on the `main` branch. Today, `filter` is parsed and stored but is **not yet evaluated at runtime** — the trigger fires on every matching `(source, event)` pair regardless of filter content. Authoring a filter is safe and will take effect once evaluation is enabled. See the [Trigger Sources reference](/reference/trigger-sources#filter-not-enforced).
  </Accordion>

  <Accordion title="Gate">
    A condition block attached to a step that controls success evaluation and failure recovery. The `success_if` field accepts a CEL expression over `exit_code`. The `on_failure.restart_from` field names an earlier step in the same job to restart from when the gate fails. The `on_failure.output` field provides a message to surface in the run log on failure. A gate must contain at least one of `success_if` or `on_failure`. See [Gate block](/reference/step-types#gate-block).
  </Accordion>

  <Accordion title="Job">
    A group of steps that runs on a single runner. Jobs within a workflow run in parallel by default; use `needs` to declare dependencies and sequence them. Each job re-clones the repository independently. A job must have at least one step. See [Job fields](/reference/workflow-schema#job-fields).
  </Accordion>

  <Accordion title="Key (step field)">
    An optional stable identifier on a step, set with the `key` field. Unlike `name` (which is a display label), `key` is intended for programmatic reference — for example, identifying a step when integrating with the Shipfox API. Must be at least one character. Valid on both run steps and agent steps.
  </Accordion>

  <Accordion title="Model">
    The AI model used by an agent step (e.g., `claude-opus-4-8`, `gpt-5.5-pro`). Specified with the `model` field on an agent step. When omitted, the model is resolved at runtime from the workspace provider configuration. Model catalog validation happens at runtime, not at parse time.
  </Accordion>

  <Accordion title="Project">
    Connects one Git repository to a Shipfox workspace. A project holds all workflow definitions and run history for that repository. Workflow YAML files live at `.shipfox/workflows/*.yml` inside the connected repository.
  </Accordion>

  <Accordion title="Provider">
    An AI model provider configured in workspace settings with an API key. Workflows reference providers by their ID string in the `provider` field of an agent step. Supported provider IDs include `anthropic`, `openai`, `deepseek`, `google`, `mistral`, `groq`, and many others. See the full list in the [Workflow Schema reference](/reference/workflow-schema#provider-ids).
  </Accordion>

  <Accordion title="Run">
    One execution of a workflow. A run contains one or more jobs, each of which contains one or more steps. Runs are triggered by a trigger event or fired manually from the dashboard. Each run records its jobs, steps, and their outcomes.
  </Accordion>

  <Accordion title="Runner">
    A process you deploy on your own infrastructure that polls Shipfox for jobs. Jobs are dispatched to runners whose labels match the job's `runner:` field. Runners execute run steps and coordinate agent steps. Multiple runners can be registered in a workspace.
  </Accordion>

  <Accordion title="Run step">
    A workflow step that executes a shell command using the `run` field. Has access to `env` variables from the workflow, job, and step scopes. Cannot be combined with agent step fields (`prompt`, `model`, `thinking`, `provider`) on the same step. See the [Step Types reference](/reference/step-types#run-step).
  </Accordion>

  <Accordion title="Step">
    The smallest unit of work in a Shipfox workflow. A step is either a run step (executes a shell command) or an agent step (invokes an AI model). Steps within a job run sequentially. Each step can optionally carry a `gate` block for success evaluation and failure recovery.
  </Accordion>

  <Accordion title="Thinking level">
    Controls reasoning depth for agent steps. Set with the `thinking` field on an agent step. Higher levels cause the model to spend more tokens on internal reasoning before producing a response, which can improve quality for complex tasks. Accepted values: `off`, `minimal`, `low`, `medium`, `high` (default), `xhigh`.
  </Accordion>

  <Accordion title="Trigger">
    Defines when a workflow run starts. Configured in the `triggers:` section of a workflow YAML. Each trigger has a `source` (the integration) and an `event` (the specific event from that source). An optional `filter` CEL expression narrows which events fire the trigger (not yet evaluated at runtime). See the [Trigger Sources reference](/reference/trigger-sources).
  </Accordion>

  <Accordion title="Workflow">
    A YAML file under `.shipfox/workflows/` that defines automation for a project: jobs, steps, triggers, and runner requirements. Versioned in your repository alongside your code. The schema is strict — unknown keys are rejected at parse time. See the [Workflow Schema reference](/reference/workflow-schema).
  </Accordion>

  <Accordion title="Workspace">
    The top-level organisational unit in Shipfox. Contains projects, runner settings, AI provider configurations, and members. Provider API keys and default model selections are configured at the workspace level and resolved at run time when not specified in a workflow step.
  </Accordion>
</AccordionGroup>