Build your first factory
Walk through the New factory wizard step by step, then edit the workflow it creates and see the same factory as a workflow file.
On this page
A factory is a workflow, at least one trigger and a set of guardrails, pointed at your repositories. The New factory wizard builds all of that in six steps. This page explains every field so you can make informed choices, then shows what to change afterwards.
Before you start, connect your repository host (GitHub, Bitbucket or Azure DevOps), where factories open pull requests, and, if you want issue triggers, Linear, GitHub Issues or Jira. See Connecting integrations.
Open the wizard
Open Factories in the sidebar and choose New factory, or press ⌘ K and type “New factory”. The wizard shows a live preview of the factory as you go, and you can step back at any point without losing what you entered.
1. Template
“Factories are a workflow, a trigger and guardrails. Start from a proven one or build from scratch.”
| Template | What it does | Default trigger | Default steps |
|---|---|---|---|
| Ship features | Issue in Ready → plan, approve, build, test, review, merge | Linear label | Size & route, Plan, Human approval, Implement, CI checks, Agent review, Ship |
| Fix bugs from Sentry | New Sentry issue → reproduce, fix with a regression test, draft PR | Sentry alert | Reproduce from the stack trace, Plan the fix, Implement, Add regression test, CI checks, Open draft PR |
| Dependency upgrades | Weekly: group upgrades, fix breakages, merge when green | Schedule, Mondays 06:00 | Scan and group upgrades, Upgrade and fix breakages, CI checks, Agent review, Ship |
| Docs & changelog | Friday: gather merged PRs, draft docs and changelog, ask for review | Schedule, Fridays 16:00, plus GitHub label docs | Gather merged PRs and diffs, Draft docs and changelog, Review copy, Open PR |
| Blank | One implement step and a PR. Build the rest yourself | None | Implement, Ship |
More templates, from Duun and the community, are on Explore. Templates installed from Explore open this same wizard with the fields filled in.
2. Basics
“What it’s called, where it works and which project its runs belong to.”
- Name: shows in the sidebar as “Name factory”. Required.
- Description: shown on the factory’s card.
- Repositories: pick at least one. Agents read these for context and open pull requests against them.
- Base branch: the branch pull requests target, usually
main. - Project: runs from this factory land in this project. Choose No project (workspace) to keep runs at the workspace level.
3. Workflow
“The steps every run goes through, in order. Each agent step picks who does it.”
The wizard shows the template’s steps as a simple list. Add steps from the menu (Plan, Implement, Test, Agent review, CI checks, Human approval, Size & route, Ship), reorder them, or remove them. For each step you choose:
- Agent for agent steps, such as builder for planning and implementing, tester for tests, reviewer for a first-pass review.
- Approver for Human approval: Issue owner, CODEOWNERS, Project lead or Anyone on the project.
- Command for CI checks, such as
pnpm ci. The check retries, then hands back. - When done for Ship: Merge on green (squash once checks and reviews pass), Open PR only (a human merges) or Draft PR (for early feedback).
The workflow needs at least one agent step: “Add at least one agent step: someone has to do the work.” You get the full editor, with branching, gates and typed references, once the factory exists.
4. Triggers
“What starts a run. Manual runs from New run, ⌘K and Slack /build always work when manual is on.”
| Trigger | Fields |
|---|---|
| Linear label | Team, Label (for example ready) |
| GitHub issue | Label, in the selected repos |
| Sentry alert | Sentry project, Threshold (events per hour) |
| Schedule | Cron, with presets such as Weekdays 09:00 or Nightly 02:00 |
| Manual | On by default: New run dialog, ⌘K, Slack /build and the API |
Turn on at least one trigger, or nothing will ever start a run. The workflow editor offers more kinds later, including webhooks and events. See Triggers.
5. Guardrails
“What agents may do without asking, and what a run may spend.”
- Approval policy: the permission mode. Ask for everything (every write and command becomes an ask, best for new factories), Ask for writes (reads and allow-listed commands run freely, recommended) or Autonomous in sandbox (no asks inside a disposable sandbox with no network; merge still gated).
- Approve plans before implementing: the run pauses after planning and asks the issue owner.
- Require human review to merge: when off, small, green PRs outside protected paths merge on their own.
- Budget per run: pauses and asks at 80%.
- Daily cap: across all runs of this factory.
- Max concurrent runs: extra runs queue.
- Protected paths: agents can read these, but any edit becomes an ask and needs CODEOWNERS review. Defaults include
.github/workflows/**,infra/prod/**and**/*.pem.
Guardrails can only tighten workspace settings, never loosen them. See Permissions and approvals.
6. Review & create
Check the summary and choose Create factory. “The factory starts paused until its first run, so nothing happens the moment you create it.” Start that first run with C, or wait for a trigger once you resume the workflow.
Edit the workflow
The wizard creates version 1 of the factory’s default workflow. To change it, open the factory and go to Workflows:
- Pick the workflow in the toolbar and switch between Summary and Graph.
- Select a step to edit it in the inspector, or describe a change in the chat pane, for example “Add a security review after Implement”.
- Fix anything listed under problems: problems block applying.
- Choose Review changes, check each step’s before and after, then Apply changes.
Applying creates version 2. Runs already in progress keep version 1. See Versions and rollback.
The same factory as a file
Every workflow can also be read and written as YAML with the Preview CLI (duun workflows pull and duun workflows apply). The Ship features template looks roughly like this:
# duun.workflow/v1
id: wf_9c1d
revision: 1
name: Features
factory: fac_platform
description: Runs the Platform team's work through to reviewed PRs.
triggers:
- kind: issue
provider: linear
team: Platform
label: ready
- kind: manual
limits:
budget_usd: 5
pause_at_pct: 80
timeout_min: 120
max_concurrent_runs: 4
inputs:
- key: issue
type: markdown
description: The issue that started the run
steps:
- id: size-route
kind: decide
name: Size & route
owner: { kind: agent, agent: builder, model: opus-5.5 }
instructions: Estimate PR count and blast radius of {{input.issue}}.
control:
mode: first_match
cases:
- id: small
label: Small
when: { name: judged, question: "Is this one PR or less, with a low blast radius?" }
activate: [implement]
otherwise: { activate: [plan] }
- id: plan
kind: agent
name: Plan with repo context
owner: { kind: agent, agent: builder, model: opus-5.5 }
instructions: Read {{trigger.issue.url}} and the repo. Write a plan with steps, risks and what's out of scope.
outputs:
- { key: summary, type: markdown, description: What it did }
- id: approve
kind: human
name: Approve plan
owner: { kind: human, who: issue_owner }
instructions: Review and approve, or send it back with a note.
gate: { type: user_approval }
- id: implement
kind: agent
name: Implement in isolated worktree
owner: { kind: agent, agent: builder, model: opus-5.5 }
depends_on: [approve, size-route]
instructions: Implement {{steps.plan.output.summary}} with tests.
outputs:
- { key: summary, type: markdown }
- id: ci
kind: check
name: CI and contract tests
owner: { kind: orchestrator }
instructions: Run the checks and report each failure with its log.
gate:
type: ci_green
command: pnpm ci
on_fail: { return_to: implement, policy: retry_with_feedback, max_attempts: 3 }
- id: review
kind: agent
name: First-pass review
owner: { kind: reviewer, agent: reviewer }
instructions: Review the diff against CODEOWNERS rules.
gate: { type: review_check }
- id: ship
kind: deliver
name: Open PR & merge on green
owner: { kind: orchestrator }
instructions: Open a PR from the run branch; merge when checks and reviews pass.
mode: merge_on_greenThe Step kinds reference explains every key. To keep a workflow in version control, see Versions and rollback.