# From a task to a pull request

At the end of this guide, a task in a Volobox project is assigned to a coding agent, the agent has worked on it in a coding session, the repository's checks have run, and a pull request is open for your team to review and merge. Linking a repository needs the project's **Manager** role or higher; starting the work needs **Collaborator** or higher on the project and the **Agent** or **Admin** role on the agent.

## Before you begin

- A code host connected to Volobox, and the repository registered under **Organization Settings** → **Code** by an administrator. See [Connect GitHub](/docs/connect-github), [Connect GitLab](/docs/connect-gitlab) or [Connect Azure DevOps](/docs/connect-azure-devops).
- A shared agent that can code: **Writes code** on under **Coding** in its settings, its **Autonomous** profile on, and membership in the project as **Collaborator** or higher.
- The agent on the repository's access list. An autonomous agent clones the repository under its own access, not yours.
- An account for the coding agent the work will run on. OpenCode runs on the organization's models. Cursor and Codex run on a person's own account. Claude Code runs only on a person's own machine signed in to their Claude subscription, never in the cloud sandbox. A team agent can also hold its own Cursor or Codex account under **Coding** in its settings.
- Optional: a [preview manifest](/docs/write-preview-manifest) with `verify` steps, so the agent's change is built and tested before the pull request opens.

## Link the repository to the project

1. Open the project, select the **Settings** tab and open **General**.
2. Turn on **Coding**, and choose **Coding on new tasks**: **Auto** (Volobox decides per task when an agent starts on it), **On** or **Off**. The project now has a **Code** tab with its pull requests, sessions and previews.
3. Open **Repositories** in the settings sidebar and click **Link repository**.
4. Select the repository and save.
5. Optional: in the row's **⋯** menu, choose **Set as default**. New coding tasks then preselect this repository.

## Assign the task to a coding agent

1. Open the task.
2. Open **Assignees**, switch to the **Agents** tab and pick the agent. A task has at most one agent.
3. On the **Coding** card, set **Mode** to **On** (or leave **Auto** to let Volobox decide when the work starts).
4. Pick the **Coding repository**.
5. Check the two options that appear once a repository and an agent are set: **Open a pull request when the agent finishes** and **Automatically start the app preview**. Both are on by default.

> **Note:** If the repository does not list the agent, a warning under the agent's row names the repository and **Start** stays off. An administrator adds the agent from **Manage repository access**.

## Start the agent's work

1. Click **Start** next to the agent on the **Assignees** card. The **Start coding work** dialog opens.
2. In **Note for the agent**, write what the agent should know beyond the task: scope, approach, things to avoid. It reads the note right after the task.
3. Choose the coding agent, the **Model** (or **Auto**) and the **Effort**. With Claude Code, your machine must be online when you start the work.
4. Choose the mode: **Agent** to do the work, **Plan** to have the agent draft a plan for your approval first, or **Ask** for an answer without code changes.
5. Check the chips under the box: the base branch, and where the session runs (**Cloud sandbox** or **Your machine**). Leave **Where it runs** as it is and Volobox decides.
6. Click **Start agent work** (or **Start planning** for **Plan**, **Ask the agent** for **Ask**).

![Fieldwork task #142, assigned to the Software Developer agent with coding on, and the Start coding work dialog over it: a note for the agent, OpenCode as the coding agent with Auto model choice in Agent mode, the meridian-works/fieldwork-app repository on main, Cloud sandbox, the task as context, and Start agent work.](https://volobox.io/docs/images/task-start-coding.light.webp)

*The Start coding work dialog: a note for the agent, the coding agent, model and mode, the repository, base branch and Cloud sandbox, and Start agent work.*

The agent works in the background under its own identity. It reads the task with its type, labels, sub-tasks, newest discussion messages and small text attachments, your note, and the repository's `AGENTS.md` (or `CLAUDE.md` when there is no `AGENTS.md`). When something is unclear, it asks instead of guessing.

## Follow and steer from the task discussion

1. Watch the **Linked coding session** row above the task's description. It shows the session's status, branch, and **View pull request**, **Open preview** and **Go to session** once they exist.
2. Follow the milestone cards in the task **Discussion**: a plan to approve, a question, **Preview ready**, **Changes ready for review**. Finished steps collapse to one line.
3. Answer a question on its card. Only the coding session's owner can answer it.
4. To change course, choose **Reply** on one of the agent's run messages, or `$mention` the agent, and write what you want: "also update the README", "use the existing date helper instead", "stop", "retry it".

The agent answers in the discussion with what it did. It passes your instruction to the coding session in its own words, because the coding agent cannot read the discussion. It acts with your rights, on the task's newest run only.

## Let the checks run

When the agent finishes its turn, Volobox runs the `verify` steps of the repository's `volobox.app.yaml` (build, test, lint) before it opens the pull request. The coding session shows **Running the repository's checks…** meanwhile.

- When a check fails, the agent gets a turn to fix it and the checks run again.
- When they still fail, the pull request opens anyway with the failure marked, and the discussion shows **Checks still fail**.
- A repository with no `verify` steps gets **Not checked**. See [Add verify steps](/docs/write-preview-manifest#add-verify-steps).

The pull request opens with the `volobox-agent` label. Its description carries the agent's **Agent confidence** (high, medium or low), and its **Verification** section lists each check with its result and time. On success, ownership of the coding session passes to the person who pressed **Start**, unless the work ran on the team agent's own Cursor or Codex account: then the session stays the agent's.

## Review the pull request

1. On the **Changes ready for review** card, choose **View pull request**. The pull request's page opens in Volobox.
2. Read the band at the top. Its chips show the checks, the review decision, the checks the agent ran before opening the pull request, its confidence, and the AI review.
3. Read the diff on the **Changes** tab and comment on lines.
4. Choose **Review** → **Submit review** and pick **Comment**, **Approve** or **Request changes**.
5. With **Request changes**, leave **Hand off to the agent** on. The coding agent receives your review comments and continues in the session on the same branch.

> **Tip:** A review someone submitted on the code host does not reach the agent by itself. Open the pull request and choose **Ask agent to address** in the **⋯** menu in its header to send the newest review that asked for changes to the coding session.

You can also review in the coding session before anything is pushed: open **File Changes**, choose **Review** on a file's diff, click lines to comment, and choose **Request changes**. That feedback goes to the coding agent only, not to the code host.

## Ask for an AI review

1. On the pull request, open **Review** and choose **Request AI review**.
2. Read the verdict (**No blocking findings** or **Fix first**), the findings on the lines they are about, and whether each acceptance criterion of the linked task is met.
3. Choose **Fix with agent** on a finding, or tick several and use **Fix N selected with agent**, to send them to the coding agent. With nothing ticked, every open **Important** finding is sent.
4. Choose **Add to my review** to take a finding over as your own review comment.

![A pull request opened by the Software Developer agent, on its Reviews tab: your review is requested, checks 4 passed, agent confidence High, and the AI review asking to fix one thing first, with acceptance criteria 2 of 3 met and an Important correctness finding about the retry counter.](https://volobox.io/docs/images/pull-request-review.light.webp)

*A pull request on its Reviews tab: an AI review that asks to fix one thing first, acceptance criteria 2 of 3 met, and a finding with Fix with agent, Add to my review and Dismiss.*

AI review is advice. It never approves, never requests changes, and never blocks a merge. **No blocking findings** means only that the reviewer found nothing blocking. The reviewer reads the repository's `REVIEW.md` from the branch the pull request targets; see [Guide coding agents](/docs/guide-coding-agents#write-reviewmd-for-the-ai-reviewer).

## Merge

1. When the pull request is ready, click **Merge**. It needs the **Pull requests** → **Merge** permission.
2. Choose a merge method, check the commit message, and decide whether to delete the branch after merging.
3. Confirm. A card follows the merge in the corner of the window.

The code host's approvals and branch protection (or Azure Repos required policies) decide whether the merge goes through; Volobox does not override them. Nothing in this flow merges a pull request by itself. When **Close task when merged** is on for the pull request, the linked task closes once it merges.

## Check that it works

- The task discussion shows **Changes ready for review** with **View pull request**.
- The pull request carries the `volobox-agent` label, **Agent confidence**, and a **Verification** section (or **Not checked**).
- After the merge, the pull request shows **Pull request merged**, and the task is closed when **Close task when merged** was on.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| A warning says **Coding is off for this agent, so it will reply in the task discussion instead of running a coding session.** | Turn on **Writes code** under **Coding** in the agent's settings (**Open its Coding settings**). |
| **Start** stays off and a warning names the repository | The repository's access list does not include the agent. An administrator adds it with **Manage repository access**. |
| The discussion shows **No files were changed** | Open the session, read the agent's last reply, then add the missing detail or ask it to try again. |
| The **Could not continue** card appears | Choose **Finish delivery** when only the commit, push or pull request is missing, otherwise **Retry coding**. You can also reply "retry it" on the card. |
| The pull request says **Not checked** | The repository's `volobox.app.yaml` has no `verify` steps. Add them for the next agent pull requests. |
| **Checks still fail** in the discussion | Read the failing check's output in the pull request's **Verification** section, then fix the code or ask the agent in its session. |
| Claude Code is greyed out in the coding agent picker | It needs a machine of yours that runs coding sessions, with **Use my Claude subscription** on and a sign-in. See [Run coding sessions on your own machine](/docs/own-machine). |

## Next steps

- [Write a preview manifest](/docs/write-preview-manifest)
- [Guide coding agents](/docs/guide-coding-agents)
- [Run coding sessions on your own machine](/docs/own-machine)
- [Coding sessions and the task-to-PR loop](/docs/coding)
