> For the index of every page in Orbital's docs, read https://docs.beta.runorbital.dev/llms.txt.

# Implement a feature

> Turn a short goal or a ticket into a reviewed, merged pull request

In this example you have Orbital build a small feature and deliver it as a merged pull request. You start one shipped workflow with the feature in plain words, or with the address of the ticket that describes it.

About five minutes to set up. The run then works on its own until the pull request merges.

## Before you start

Both workflows ship with Orbital, so there is nothing to download. You need:

- a project whose primary folder is a Git repository with a GitHub remote you can push to, because the run works in a [worktree](/projects/worktrees-and-delivery/) and delivers a pull request;
- a GitHub token Orbital can use: a `gh auth login`, or a token in **Settings > GitHub**;
- a harness that is installed and signed in;

For `implement-ticket` with a Linear ticket, the agent reads it with the Linear tools your harness has, such as Linear's MCP server.

:::caution
Orbital turns on auto-merge for the pull request. Where your branch rules require no review, the pull request merges as soon as its required checks pass. With no required checks, it merges as soon as it opens. Protect the branch before you start, or start your own copy of the workflow with auto-merge removed from its delivery. [Turn auto-merge off](/projects/worktrees-and-delivery/#turn-auto-merge-off) shows how.
:::

The steps run with Full access. `pursue-goal` also runs with `permissions="full"`, so its agent is never asked before it changes files or runs commands. `implement-ticket` uses `auto-accept`. [Permissions](/roles/#permissions) explains what each one asks you.

## 1. Choose a workflow

| Use | When |
| --- | --- |
| `pursue-goal` | You can say what you want in a few sentences, and there is no ticket. |
| `implement-ticket` | The work is written up in a GitHub or Linear issue. |

Both work in a worktree, review their own work and verification, open a pull request, and repair it until it merges.

## 2. Start the run

Follow the part for the workflow you chose.

### Deliver a goal with pursue-goal

**App**

1. Choose **New task**, pick the project and choose the `pursue-goal` workflow.

![The Start page asking what to do in a project, with a goal box, a harness picker, a workflow picker and a Chat or Workflow switch.](/screenshots/start-page.webp?v=0428f5d705)

*Pick the workflow, then write the goal in the box.*

2. Write the goal. Say what should change, how you will know it works, and any rule the result must follow. For example:

   ```text
   Add a "Copy link" button to each invoice row. Clicking it copies the
   invoice's public address. Add a unit test for the address format.
   Follow the conventions in CONTRIBUTING.md.
   ```

3. Choose **Start run**.

**Command line**

Run `orbital run start` with your project's id and the goal. [The orbital command](/reference/command/) lists every flag.

```sh
orbital run start --workflow pursue-goal --project proj_r3tQMqBPBB5p \
  --goal "Add a Copy link button to each invoice row. Clicking it copies the invoice's public address. Add a unit test for the address format."
```

![pursue-goal: create_worktree, implement, validate, then delivery, cleanup and the terminals.](/shipped/pursue-goal.svg?v=dc2465a951)

What the run does:

| Step | What it does |
| --- | --- |
| **create_worktree** | Makes a worktree on a new branch. |
| **implement** | Changes the code and commits. |
| **validate** | Checks the work against every point of the goal, using the change and verification. If something is missing, it sends feedback back to **implement**. This loop runs at most 20 times. |
| **delivery** | Opens the pull request and waits for it to merge, repairing CI, conflicts and review comments. |
| **cleanup** | Removes the worktree once nothing in it would be lost. |

Implementation goes straight to validation. A rejected validation returns its feedback to the next implementation round; a pass starts pull request delivery. There is no separate checks or prerequisite gate.

### Deliver a ticket with implement-ticket

**App**

1. Choose **New task**, pick the project and choose the `implement-ticket` workflow.

2. Fill in **Ticket URL**, such as `https://github.com/acme/app/issues/628`.

3. Write a goal, or leave the ticket to speak for itself.

4. Choose **Start run**.

**Command line**

Give the ticket's address as the `ticket_url` input.

```sh
orbital run start --workflow implement-ticket --project proj_r3tQMqBPBB5p \
  --input ticket_url=https://github.com/acme/app/issues/628
```

![implement-ticket: scope, then the deliver-ticket sub workflow.](/shipped/implement-ticket.svg?v=82fe3ab50a)

The first step reads the ticket and writes the scope that every later step works from. Then the run plans, implements, and has the change reviewed against the ticket and verification. A rejected review revises the plan and the implementation, and the review runs again. Once the review passes, the run delivers the pull request the same way as `pursue-goal`. It completes the ticket after the merge.

## 3. Follow the run

| Where | What it shows |
| --- | --- |
| The **Session** tab | Each step and the agent's work. |
| The dock's **Changes** tab | The diff so far. |
| The dock's **Pull requests** section | The pull request, once it is open. |

![A run page on the Session tab showing the steps one by one, with Run facts, Pull requests and Steps in the dock on the right.](/screenshots/run-thread.webp?v=f4f203d47e)

*The Session tab shows each step; the dock lists the run's pull requests.*

To steer the run, write in the composer. To change what the run should do, send it a message with the new requirement. See [Message a run](/runs/message-a-run/).

## 4. Review the pull request

While the pull request waits for review, the run waits at a gate, "The pull request is waiting for review or merge". It takes no run slot. Review the pull request as you normally would. You do not need to merge it: once your branch rules allow, GitHub merges it, because Orbital turned on auto-merge. Orbital looks at the pull request once a minute and carries on by itself.

![A gate step saying the pull request is waiting for review or merge, with the waiting time, the next check and a Skip button.](/screenshots/gate-wait.webp?v=fdf72f63d4)

*The run waits here without taking a run slot.*

## What you get

The run ends Succeeded when the pull request merges. It ends Failed when someone closes the pull request without merging. See [standings](/runs/#standings).

![The dock's Pull requests list with open and merged pull requests and their branches.](/screenshots/pull-requests-panel.webp?v=612ac483b1)

*A merged pull request shows as merged in the dock.*

Once the publish step ends, Orbital turns on auto-merge for the pull request itself, with your GitHub token. The agent never runs `gh` for it, so this works on every harness and permission setting. When the repository does not allow auto-merge, a rule blocks it, or the token lacks permission, the run's history says so and the run carries on. Then merge that pull request yourself. [Turn auto-merge off](/projects/worktrees-and-delivery/#turn-auto-merge-off) explains how to stop Orbital asking.

## Related

- [Worktrees and delivery](/projects/worktrees-and-delivery/): how the run makes a worktree, opens the pull request and merges it
- [Shipped workflows](/reference/shipped-workflows/): every step of `pursue-goal` and `implement-ticket`
- [Lead delivery with a supervisor](/supervisor/lead-delivery/): have an agent start and follow such runs for you
- [Deliver an epic](/examples/deliver-an-epic/): deliver many tickets in one run