Skip to content
Source
Sign inSign up

Drafts, reviews and updates of pull requests

You open a pull request before the work is done, and nobody must merge it yet. Later you need reviewers, your branch falls behind its base, or a merge breaks the base branch.

Each step below works on its own. Do only the steps that you need. To change several members of a monorepo in one pull request, see Change several members in one pull request.

1. Open a draft

Push your branch. Then, in your clone:

src pr create --draft --title "Count down to zero" --body "Work in progress"
  • Nobody can merge a draft. Its merge box says This pull request is still a draft, and the merge button stays off.
  • The factory agents skip a draft. They start when you mark it ready for review.
  • To make an open pull request a draft again, click Convert to draft in its sidebar, or run src pr ready 7 --undo.

The author of a pull request can change its draft state. So can people with write access.

2. Mark it ready for review

On the web, open the pull request, then click Ready for review in its merge box.

In a terminal:

src pr ready 7

When the factory is on, its agents now start on the pull request, as on a new one. For example, the Impact tab then shows whether the pull request changes the architecture or the public API. See Read the Impact tab.

People with write access can merge it.

3. Ask for reviews

Ask when you open the pull request:

src pr create --fill --reviewer ana,ben

Or ask later, on the web:

  1. Open the pull request.
  2. In the sidebar, next to Reviewers, click Edit.
  3. In Ask someone to review, type a username, then click Add.
  4. Click Apply.

To stop asking a person, click the X next to the name, then click Apply.

In a terminal:

src pr edit 7 --add-reviewer ana --remove-reviewer ben
  • You need the triage role or more to ask for reviews.
  • Nobody can ask the author of the pull request to review it.
  • A pull request has at most 25 review requests at a time. A request ends when that person submits a review.
  • A reviewer finds the requests with src pr status, under Requesting a code review from you.

4. Bring your branch up to date

When the base branch moves on, the merge box says This branch is out of date with the base branch.

  1. Open the pull request.
  2. Click Update branch to merge the base branch into your branch.
  3. For a rebase, click the arrow next to Update branch, then click Update with a rebase.

In a terminal:

src pr update-branch 7
src pr update-branch 7 --rebase
  • You need write access to the repository of the head branch.
  • For a pull request from a fork, the author can allow maintainer edits. Then people with write access to the base repository can update it too.
  • If the two branches conflict, the forge refuses the update. Merge the base branch on your machine, then push.
  • If someone pushed to the branch after you opened the page, the forge refuses the update. Load the page again.

5. Revert a merge that broke something

On the web:

  1. Open the merged pull request.
  2. In the box This pull request is merged, click Revert.
  3. In the dialog, click Revert.

In a terminal:

src pr revert 7
  • The forge makes a new branch from the base branch, with a commit that undoes the pull request. Then it opens a pull request from that branch.
  • src pr revert prints the URL of the new pull request. --draft opens it as a draft. --title and --body set its text.
  • You need write access.

Merge the new pull request as any other, and the changes leave the base branch.

Done

Your pull request was a draft until it was ready. It has its reviewers, and it is up to date with its base branch. People with write access can merge it. If a merge goes wrong, one more pull request undoes it.

src pr status shows the pull request of your current branch, the open pull requests that you created, and the ones that wait for your review.

Later: sync your fork

Your fork falls behind its parent repository. Bring its default branch up to date.

On the web:

  1. Open the home page of your fork.
  2. Above the files, click Sync fork.

In a terminal:

src repo sync you/app
src repo sync
  • With a repository name, the forge moves the default branch of that fork to the commit of the same branch in its parent. --branch picks another branch.
  • Without a name, src updates the branch in your clone from its remote.
  • If the branch of your fork has commits that the parent does not have, the forge does not move it. On the web, click Discard my commits to reset it to the parent. In a terminal, add --force.
  • You need write access to the fork. An agent cannot sync a fork.

Later: REST and MCP

An agent or a script does the same work over REST or MCP, with the same rules. The REST paths are under /api/v1/repos/{owner}/{repo}.

You want toRESTMCP tool
Open a draft, with reviewersPOST /pulls, with "draft": true and "reviewers"create_pull_request
Mark a draft ready, or make it a draft againPUT or DELETE /pulls/{n}/readyset_pull_draft
Ask for reviews, or stop askingPOST /pulls/{n}/reviewers, with { "add", "remove" }request_reviewers
Bring the branch up to datePOST /pulls/{n}/update-branch, with { "rebase", "sha" }update_pull_branch
Revert a merged pull requestPOST /pulls/{n}/revert, with { "title", "body", "draft" }revert_pull
Sync a forkPOST /sync, with { "branch", "force" }sync_fork

A conflict in a branch update gets 409. Use the REST API has the other routes.