# Shipyard > Shipyard is MergeHarbor's coding agent. Hand it a task, approve its plan, and get a tested pull request that MergeHarbor reviews. Playbooks, toolchains, triggers and limits. Shipyard is MergeHarbor's coding agent. You hand it a task, it drafts a short plan, and once the plan is approved it makes the change in an isolated sandbox, runs your tests and lint there, and opens a pull request that MergeHarbor reviews like any other. Shipyard has its own section in the console, **Shipyard**, with six pages: | Page | Path | What it is for | | ---------- | ---------------------------- | ------------------------------------------------------------------------ | | Overview | `//shipyard` | What Shipyard has done and what is running right now | | Tasks | `//shipyard/tasks` | Every task, grouped by what needs you | | Playbooks | `//shipyard/playbooks` | Reusable instructions for recurring changes | | Toolchains | `//shipyard/toolchains` | Reusable sandbox setups attached to repositories | | Triggers | `//shipyard/triggers` | Tasks that start from an issue, an alert or a webhook | | Settings | `//shipyard/settings` | Limits, budget, network, blocked paths and auto-approve (administrators) | ## Plans and billing Shipyard is a paid add-on on every plan: Essentials, Team, Advanced and Enterprise. It costs $15 per active developer per month, or $12 billed annually, and counts the same active developers as your plan. Task runs also use credits from your pooled allowance (see [Cost and limits](#cost-and-limits)). - **Trial.** A billing admin can start a 14-day trial once per organization under **Billing → Plan**. Nothing is charged for the add-on during the trial; task runs still use credits. During a Team trial, the Shipyard trial ends when the Team trial does. - **Enterprise.** Add Shipyard under **Billing → Plan** at your Enterprise add-on price. If MergeHarbor bills you on invoice, contact support and we add it to your invoice. - **When it ends.** After a trial ends without Shipyard being added, or after it is removed, new tasks can't start and plans can't be approved. Your task history stays readable for 30 days. ## How a task runs 1. **You hand it a task.** Pick a repository and base branch, describe the change, and optionally pick a playbook, link an issue and name the files or directories to focus on. Choose a tier; Shipyard shows the credits estimate and the cap before you start. 2. **Shipyard plans.** The plan lists the files it expects to touch, the approach, and the tests it will add. By default it waits for someone allowed to approve it. Your organization can turn on auto-approve (see [Settings](#settings)). 3. **Shipyard works in the sandbox** on a new branch, `mergeharbor/task-`. Each step reads and searches your code through the code graph, edits files, and runs your tests and lint in the sandbox. It keeps going until the change is done and the checks pass, or until a limit stops it. 4. **Shipyard opens the pull request** into your base branch with the plan, a summary, the tests it ran and the credits it used. MergeHarbor's review then runs on the pull request, and the task shows the review and the [merge gate](https://mergeharbor.com/docs/merge-gate). You can follow every step live on the task's page and cancel at any time before the pull request opens. ## Where you can start a task - **Console**: **Shipyard → Tasks → New task**. Describe the change in the prompt box and set the repository, base branch, playbook, tier and credits cap with the buttons inside it; the line under the box shows the estimated credits, whether you approve the plan first and the branch the pull request targets. **Start from** fills the request from a Jira, Linear, GitHub, GitLab or Azure Boards issue, a playbook, a security finding or a vulnerability, and links it to the task. Press ⌘ Enter (Ctrl Enter) to start. - **Chat**: mention MergeHarbor in a Slack, Microsoft Teams or Google Chat channel mapped with the **fix** or **approver** role, for example `@MergeHarbor task: add a burst option to the rate limiter in acme/api`. Add `on branch release/2.1` for another base branch, or `tier deep` for a deeper tier. If the channel is mapped to one repository you can leave the repository out. MergeHarbor answers in the thread with the plan and **Approve plan** and **Cancel** buttons, then updates that message as it works. - **Issues**: **Implement this** on an issue in the console starts a task prefilled from the issue; its plan and pull request reference the issue. In chat, paste the issue link: `task: implement https://github.com/acme/api/issues/87`. - **API**: `POST /api/v1/orgs/{org}/coding-tasks` takes the same fields as the console (see the API reference). `GET /api/v1/orgs/{org}/repos/{repo_id}/branches?q=` lists the branches you can target. - **Triggers**: an issue, an alert or a signed webhook can start a task on its own (see [Triggers](#triggers)). ## Who can do what - Starting, approving and cancelling a task needs the **pulls.fix** permission on the repository. Owners and admins have it by default. - Creating and editing organization playbooks needs the **playbooks.manage** permission. Anyone who can start tasks can keep personal playbooks. - From chat, you must link your MergeHarbor account, the channel must be mapped to the repository with the **fix** or **approver** role, and your MergeHarbor role must still allow it. - In **fix** channels the requester or an approver approves the plan. In **approver** channels only an approver can, even for their own requests. ## Overview The Overview is the first page of the Shipyard section. For the period you pick it shows: - **Activity**: tasks started, pull requests opened and merged, the merge rate, the median time to merge, credits used, credits per merged pull request, and how many people started tasks. - **Breakdowns** of the same numbers by repository, by person and by playbook, so you can see where Shipyard's pull requests land and which playbooks get merged. - **Right now**: tasks planning and running, plans waiting for approval, and open pull requests. This panel is the present, not the period. ## Tasks **Tasks** lists every task in four groups: - **Needs attention**: plans waiting for approval, and tasks that stopped for a reason a person can act on: a cap or budget to raise, failing checks to fix, a branch or path to change, or a stalled task whose instructions need to be clearer. - **Working**: tasks that are queued, planning or running. - **Done**: tasks whose pull request opened, and cancelled tasks. - **Failed**: tasks that failed for any other reason, such as the sandbox or the code host failing, or nothing to change. Search, and filter by repository, requester (you, or anyone), source (console, chat, issue, API or trigger) and pull request. Pin the tasks you are following to keep them at the top, and select finished tasks to archive them in bulk; show archived tasks with the archived filter. Archived tasks still count in the Overview. ## Playbooks A playbook is a set of instructions in markdown for a change your team makes again and again: adding an API endpoint, upgrading a dependency, fixing a flaky test. Pick a playbook when you start a task, or have a trigger use one, and Shipyard follows it. - **Personal or organization.** Personal playbooks are yours. Organization playbooks are shared with everyone and need the **playbooks.manage** permission to create or edit. - **Versions.** Every save is a new version. Open a playbook's history to see who changed what, compare two versions, or restore an earlier one. A trigger can follow the current version or stay on a fixed one. - **Usage.** Each playbook shows how many tasks used it; the Overview breaks merged pull requests down by playbook. - **Import and export.** Export any version as a `.md` file, and import a file to create a playbook. ### Playbook files A playbook file is markdown with YAML front matter between `---` lines: ```markdown --- title: Add an API endpoint scope: organization version: 3 default_repository: acme/api default_paths: [internal/api] default_tier: deep --- Add the handler under internal/api and register its route. Cover the success and error cases in one table test, and update the OpenAPI spec in the same pull request. ``` | Key | Required | Meaning | | -------------------- | -------- | ------------------------------------------------------------ | | `title` | Yes | The playbook's name | | `scope` | No | `personal` or `organization` | | `version` | No | Informational only: an imported playbook starts at version 1 | | `default_repository` | No | The repository a task starts in, by full name (`acme/api`) | | `default_paths` | No | The files or directories to focus on | | `default_tier` | No | `standard`, `deep` or `max` | Everything after the front matter is the instructions. Unknown keys and malformed values are refused, with a message for each field. ## Toolchains A toolchain is a reusable sandbox setup: how to install, set up, test and lint a kind of repository. Attach a toolchain to the repositories it fits; each repository uses at most one. Without one, tasks use a setup MergeHarbor detects from the repository: its `.mergeharbor/sandbox.yml` when it has one (the same file [proof runs](https://mergeharbor.com/docs/proof-runs) use), otherwise its language, lockfiles and test runner. A toolchain has: - **Runtime or image**: a runtime, or a base image from your installation's allowlist. - **Commands**: install, setup, test and lint. - **Cache paths**: dependency directories kept between tasks, such as `~/go/pkg/mod` or `node_modules`. - **Network**: none, or allowlisted package registries only. - **Variables and secrets**: plain variables, and secrets that are write-only and sealed. Nobody can read a secret back once it is saved, and its value is redacted from everything Shipyard shows. **Run check** runs the toolchain's setup on one repository in the sandbox, so you know it works before a task needs it. Each repository shows whether its toolchain is ready, failing or never checked. A check uses 1.2 credits per sandbox minute. ## Triggers A trigger starts a task automatically when: - an issue is **opened** or **labelled** in GitHub, GitLab, Jira, Azure Boards, Linear or Asana, - **Sentry**, **Datadog** or **PagerDuty** raises an alert or incident, or - a **signed webhook** arrives at the trigger's own URL. Each trigger picks the **repository**, an optional organization **playbook** (its current version or a fixed one), the **tier**, the **credits cap** per task, the **base branch**, and a **daily cap** from 1 to 50 tasks (5 by default). A trigger starts at most one task per issue or incident, even if the event arrives twice. The trigger's **instructions** say what to do, and default to: ```text Resolve {{key}}: {{title}} ``` These placeholders are filled in from the issue or incident: | Placeholder | Filled with | | ------------ | ------------------------------------------ | | `{{title}}` | The issue or incident title | | `{{key}}` | Its key or number, such as `ACME-212` | | `{{url}}` | A link to it | | `{{source}}` | Where it came from, such as Jira or Sentry | | `{{labels}}` | Its labels | The issue's description reaches Shipyard separately, as untrusted content. The plan of a triggered task waits for a person's approval unless **auto-approve for triggers** is turned on in Settings. ## Cost and limits Each tier has a fixed price per step, so you know the cost before you start: | Tier | Credits per step | Credits per sandbox run | Typical task | Default cap | Steps | | -------- | ---------------- | ----------------------- | ------------ | ----------- | ----- | | Standard | 1 | 1 | 8 | 15 | 12 | | Deep | 2 | 1 | 24 | 40 | 20 | | Max | 4 | 1 | 60 | 100 | 30 | Planning counts as one step. A task never uses more than its credits cap, and it stops at the step limit and the organization's time limit. A task that changes no file in three steps in a row stops as stalled, so it does not use its whole cap going in circles. Credits used are charged even when a task stops or is cancelled, and only for the steps it used. ## Settings Shipyard is off until an administrator turns it on under **Shipyard → Settings**, where you also set: - **Limits**: the default tier, how many tasks run at once (more wait in the queue), the most steps and minutes per task, and the highest credits cap a requester can choose. - **Monthly coding-task budget**: the credits all tasks can use per month. The caps of tasks that are still running are reserved against it, so a new task that could go over it is refused, and a running task never uses credits another task holds. Your organization's overall budget and monthly credit limit apply too: with **Pause reviews** at the limit, no task starts a step past it. - **Auto-approve**: let plans start without a separate approval, separately for tasks started in the console, from chat channels with the fix or approver role, and from triggers. All are off by default. - **Write as requester**: commits name the person who asked as the author. Otherwise MergeHarbor's app authors them. - **Sandbox network**: none (the default), or only your installation's package registries while dependencies install. - **Blocked paths**: files tasks never edit. `.github/workflows/**` is blocked by default; `.git` and `.mergeharbor/` always are. ## Safety - The sandbox has no network by default and never receives your code-host credentials or model keys. Toolchain secrets are passed only to the sandbox commands. - Playbook, issue and alert text is treated as untrusted guidance: it shapes the change, but it cannot lift a limit, a permission or a blocked path. - Shipyard only pushes to its own `mergeharbor/task-` branch. It never pushes to your base branch or any protected branch. - Edits that look like they add a secret are refused, and everything shown in the console, chat and the pull request is redacted. - Every task is recorded in the audit log: created, approved, cancelled, failed, and pull request opened. Toolchain changes and readiness checks are recorded too. Shipyard tasks run in repositories connected through the MergeHarbor GitHub App.