Getting Started with Shipfox: Run Your First Workflow
Connect a project, add a workflow, and verify a command and agent step in your first Shipfox run.
In this lesson, you will connect a test repository and run one complete workflow. The final run prints a command result and contains an agent summary based on the repository's files.
Before you begin
This lesson assumes that you can sign in to a workspace, a source integration connection
can read the test repository, an ubuntu-latest runner is online, and the
workspace has configured agent
defaults. See
Installation if Shipfox is not running yet.
Connect your project
A project connects one repository to Shipfox and is the container for all workflows, runs, and settings related to that repo.
Create a project
Open your Shipfox workspace dashboard and create a project. Pick the source integration connection, then the repository. The project name is pre-filled from the repository and can be edited.
Connect the repository
Shipfox reads workflow files from .shipfox/workflows/ in the default branch. No extra configuration is needed: any .yaml or .yml file in that directory is treated as a workflow definition.
Add your first workflow
A workflow is a YAML file that tells Shipfox when to run (triggers), where to
run (runner), and what to do (jobs and steps). Create
.shipfox/workflows/hello.yaml. This is a complete workflow:
name: Inspect the repository
runner: ubuntu-latest # label of the runner that executes the jobs
triggers:
on_demand:
source: manual # fires when you click Run in the dashboard
event: fire
jobs:
inspect:
steps:
- run: echo "hello world"
- prompt: |
Read this repository and summarize its purpose in two sentences.
Name one top-level file that supports your answer.
Do not change any files.The manual trigger works in every workspace with no further setup. Every field is described in the Workflow Schema reference.
Commit and push the file to the repository's default branch. Shipfox detects the workflow automatically. No manual import is required.
Run it
A run records one use of a workflow. Open the project's Workflows page, find Inspect the repository, and select Run.
Open the run to stream its output. The command step should show:
inspect · echo "hello world"
hello world
A run detail page: status, the job graph, and every step with its duration.
A run stuck in pending means no online runner matches the runner: label in your workflow. Check that a runner with the label ubuntu-latest is online. See Resolve pending jobs.
Verify the result
Open the agent step after it finishes.
- Confirm that the response has two sentences.
- Open the file named by the agent and check that it supports the summary.
- Confirm that the agent did not change any repository file.
The agent uses the checkout for the commit that started the run. Its messages, tool calls, token use, cost, and final response remain in the step log.
What you built
You connected one repository, synced a complete workflow, and started it with a manual trigger. One job ran a fixed command and an agent in the same checkout. The run now provides a visible record of both steps and their results.
Next steps
How Shipfox works
The mental model in one page: events, jobs, agents, and feedback loops.
Parallel CI and agent review
Run lint and tests together, then review the repository after both pass.
Gate & retry
Add an objective check and retry an agent with evidence.
Agent steps
Add and verify agent work in another workflow.
Checks on every push
Replace the manual start with a GitHub push trigger.