Skip to main content
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.
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.
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 for syntax details.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.