> ## 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.
# Introduction to Shipfox: Agentic Workflow Automation
> Shipfox runs YAML workflows from your repo, treats AI agents as first-class steps, and turns events from your tools into native triggers — GitHub, Sentry, any webhook, and more on the way.
Shipfox runs **agentic workflows** from your repository. A workflow is a YAML file in `.shipfox/workflows/` — triggers, jobs, steps, runners — a shape you already know how to read. The difference is what a step can be: a step runs a shell command **or runs an AI agent** — a `model`, a `prompt`, and your repository checked out. Agents and commands share one lifecycle, so a gate can retry an agent until your tests pass, and every agent step records a full session: messages, thinking, tool calls, token usage, and cost.
```yaml theme={null}
name: Fix Sentry issues
runner: ubuntu-latest
triggers:
on_issue:
source: sentry_acme # fires when Sentry reports a new issue
event: issue.created
jobs:
fix:
steps:
- key: install
run: npm ci
- model: claude-opus-4-8
prompt: >
Sentry reported "${{ event.title }}" (${{ event.webUrl }}).
Find the cause in this repository and fix it.
- run: npm test
gate:
success_if: exit_code == 0
on_failure:
restart_from: install # loop until the tests pass
```
If you've written GitHub Actions, you already know how to read this file — that's deliberate. What's different is what a step can do — and the control flow around it: a Sentry event starts the run, the event's data lands in the agent's prompt, and the gate loops the agent until the tests pass. Agents run on any of 30+ model providers with your own API keys, on runners you own. Every run — including the agent's full transcript — streams live to the dashboard.
## How it works
Write a YAML file under `.shipfox/workflows/` in your repository. Commit and push — Shipfox picks it up automatically without any manual import step.
Choose when the workflow runs: on a GitHub push, a Sentry issue, a webhook from any system, or on demand from the dashboard — with more integrations on the way. Each trigger is a named entry under the `triggers` key in your workflow YAML.
Each job executes on a runner you register with Shipfox. Jobs are fully isolated — each one re-clones the repository before executing, so no state bleeds between runs.
Each job contains one or more steps. A step runs a shell command (`run`) **or an AI agent** — specify a `model` and a `prompt` and it reads your repo, runs tools, and acts. Agent steps are first-class: same lifecycle as shell steps, so they stream output, report status, and can be gated and retried until the result is correct.
Open the Shipfox dashboard to stream logs for every run, job, and step in real time. Drill into any step to see its full output, duration, and exit status.
The same flow as one picture — note that the runner **polls outbound** (nothing connects into your compute), and that the agent step and its gate loop sit inside the ordinary step sequence. Click the diagram to enlarge it.
## Core concepts
The YAML files that define your automation — name, triggers, jobs, steps, and environment variables.
How work is structured and executed inside a workflow, including shell steps, agent steps, and gate conditions.
What starts a run — GitHub pushes, Sentry issues, webhooks from any system, manual fires — with more integrations on the way.
The processes you register on your own compute that execute jobs. Runners poll Shipfox and are matched to jobs by label.
## Shipped vs. roadmap
Features listed as roadmap are not yet available and should not be relied upon in production workflows.
| Feature | Status |
| ------------------------------------------------------------------------ | -------------- |
| Manual triggers (`source: manual, event: fire`) | ✅ Shipped |
| GitHub push triggers (`event: push`) | ✅ Shipped |
| Sentry issue triggers | ✅ Shipped |
| Shell run steps (`run`) | ✅ Shipped |
| Agent steps (`model` + `prompt`) | ✅ Shipped |
| Gate / restart\_from (`gate.success_if`, `gate.on_failure.restart_from`) | ✅ Shipped |
| Multi-job DAGs (`needs`) | ✅ Shipped |
| Trigger filter evaluation (`filter`) | 🔜 Roadmap |
| Expression interpolation (`${{ }}`) | ✅ Shipped |
| Listening jobs (`listening: on/until` — react to events inside a run) | 🚧 Coming soon |
| Cron triggers (`source: cron` — run on a schedule) | 🚧 Coming soon |
| `loop`, `matrix`, `branch` step kinds | 🔜 Roadmap |
| GitLab push triggers | 🔜 Roadmap |
## What you can build
Run tests, lint, and get an AI review on every commit — automatically, in one workflow that lives with your code.
Let an agent read your codebase and propose or apply a fix directly from a Sentry issue or a failing test.
Retry a step until tests pass using `gate` with `success_if` and `on_failure.restart_from` — no custom scripting needed.
Coming soon: a job that listens for PR review comments and runs an agent per batch until the PR merges.