Shipfox

Shipfox Glossary: Key Terms and Concepts

Definitions for every Shipfox term: workspace, project, workflow, run, job, step, trigger, runner, harness, 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.

Agent session

The structured record an agent step produces: every model message, thinking block, tool call, and tool result, plus token usage and cost. The dashboard renders it as a transcript, live while the step runs and persisted after. See Agents. A step can also name its session with the session field. Later agent steps in the same run then continue that conversation. See Agent sessions.

Agent step

A workflow step that invokes an AI model. Defined with prompt (required), plus optional model, harness, thinking, provider, and session 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 Agent step fields.

CEL expressions

Common Expression Language, the expression language Shipfox uses for ${{ }} templates and for predicate fields such as filter, if, gate.success, and job success. See Expressions for the syntax and Contexts for the data each field can read.

Job execution

One firing of a job. A regular job has exactly one execution per run attempt; a listening job fires one execution per event batch. Job status is derived over all executions. See Jobs and steps.

Feedback loop

The pattern a gate enables: an agent acts, a check judges the result, and on failure the job restarts from the agent with feedback, within bounded attempts. See Feedback loops.

Event filter

An optional CEL expression on a trigger (or on a listening job's on/until entries) that narrows which events fire it. For example, event.ref == "refs/heads/main" on a GitHub push trigger restricts to pushes on main. The filter is evaluated when the event arrives: a false result skips the event, and an expression error fails closed. See Expressions and the trigger fields.

Gate

A check on a step. The gate decides whether the step passed. It also decides what the job does when the step fails. success is the check, and on_failure is one restart rule or a list of rules. See Feedback loops and the gate fields.

Agent harness

The agent runtime that executes an agent step. Set with the harness field: pi (the default) or claude (the Claude Agent SDK). The harness determines which thinking values the step accepts. See Agent step fields.

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 execution gets a fresh repository checkout. A job must have at least one step. See Job fields.

Step key

The ID of a step. You set it with the key field. Other parts of the workflow use the key to find the step. The name field is only a label.

Use the key to:

  • Read the outputs of the step with steps.<key>.outputs.
  • Restart the job from the step with gate.on_failure.restart_from.
  • Wait for or stop a background step with wait or cancel.

A key has at least one character. You cannot set key on a wait, wait_all, or cancel step.

Listening job

A job with a listening: block. After its needs are met it activates and fires one execution per matching event batch (new review comments, new issue events) until a resolution condition is met: an until event, a timeout, or max_executions. See Listening jobs.

AI model

model selects an agent model, such as gpt-5.6-luna. The workspace provider supplies a default. Shipfox validates the model at runtime.

Pipeline terminology

An informal synonym for workflow sometimes used in product copy. The schema, the API, and these docs use workflow.

Project

The unit in a workspace that owns workflow definitions and run history. A project has one config source: a Git repository linked through a source integration connection, or a repository Shipfox hosts, called managed config. Workflow YAML files live under .shipfox/workflows/ in that source. A managed project can move to a repository later.

Model 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. See the full catalog in the Model Providers reference.

Step and job outputs

Typed values a step declares and produces (outputs: on a step), readable by later steps as steps.<key>.outputs and lifted to downstream jobs through job outputs. See Step outputs.

Run

The record created when a workflow starts for one event or manual action. A run contains one or more attempts, jobs, job executions, and step attempts. It keeps their inputs, logs, outputs, and outcomes.

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 agent steps; the Shipfox API executes tool steps while the runner waits. Multiple runners can be registered in a workspace. See Runners and execution environments.

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, harness, thinking, provider, session) on the same step. See Run step fields.

Secret

A sensitive value stored write-only in workspace settings and bound into a run step's command or env with ${{ secrets.KEY }}. The value resolves on the runner at execution time and is masked in logs; it never appears in prompts or predicates. See Manage secrets and variables and Context availability.

Workflow step

One unit of work in a job. A step runs a shell command, an AI agent, or an integration tool. By default, steps run one after the other. A background step or a parallel block runs at the same time as other steps. See Jobs and steps.

Tool step

A workflow step that calls one integration tool with inputs the workflow supplies. Defined with tool (required), plus optional connection, with, and an outputs mapping over result. Shipfox makes the call on its API through the integration connection, so the runner never sees the credential or the arguments. See Tool step fields.

Thinking level

Controls reasoning for agent steps. Set the thinking field on an agent step. Higher levels spend more tokens on internal reasoning before a response. They can improve quality for complex tasks. Accepted values depend on the harness. Omitting the field uses configured defaults or xhigh. Set default to use the provider default without workspace or deployment overrides. See Agent step fields.

Workflow trigger

Defines when a workflow run starts. Configured in the triggers: section of a workflow YAML. Each trigger has a source (an integration connection slug or built-in source) and an optional event from that source. An optional filter CEL expression narrows which events fire the trigger, evaluated when the event arrives. See the trigger fields and integration event catalogs.

Variable

A readable configuration value stored in workspace settings and injected into workflows with ${{ vars.KEY }}, resolved when the run is created. Use variables for non-sensitive config; use secrets for credentials. See Manage secrets and variables.

Workflow

A YAML file under .shipfox/workflows/ that defines automation for a project: jobs, steps, triggers, and runner requirements. Versioned in the project's config source: your repository alongside your code, or managed config. The schema is strict: unknown keys are rejected at parse time. See the Workflow Schema reference.

Workspace

The top-level organisational unit in Shipfox. Contains projects, integration connections, runners, secrets, variables, AI provider configurations, and members. Provider credentials and default model selections are configured at this level and resolved at run time when a workflow step omits them.

Was this page helpful?
Edit this page on GitHub

On this page