Change several members in one pull request#

You add a field to the API in acme/web and explain it in acme/docs. With one pull request in each member, a reviewer must find both, and one can merge while the other waits.

Open one monorepo pull request. It holds one normal pull request in each member that it changes. Each of these is a part. One page shows all the parts, and one action merges them all.

You need a checkout from src monorepo clone, and write access to each member that you change.

1. Commit on a branch in each folder#

In each member folder that you change, make a new branch and commit:

cd platform/web
git switch -c add-field
git commit -am "Add the field"
cd ../docs
git switch -c add-field
git commit -am "Document the field"

• Use a new branch, not the default branch. src refuses commits on the default branch.
• A change to the root files of the monorepo is a part too. Its folder is ..

2. Open the monorepo pull request#

At the root of the checkout, run:

src monorepo pr create --title "Add the field" \
  --body "The API gets the field, and the docs explain it." \
  --part-title web="Add the field to the API" \
  --part-title docs="Document the field"

src finds each folder whose branch has commits that its default branch does not have. It pushes each of these branches, then opens one part in each folder:

acme/platform#12
web: acme/web#31
docs: acme/docs#8

• --part-title FOLDER=TITLE gives a part its own title. Without it, the part gets --title.
• --part-body FOLDER=BODY gives a part its own description. Without it, the description is empty.

Run the other src monorepo pr commands on this page at the root of the checkout too. In another folder, add -R acme/platform.

3. Review the parts#

1. Open the monorepo, then the Monorepo pull requests tab. Only a monorepo has this tab.
2. Click the monorepo pull request.

The page shows each part:

• Its folder and its pull request, for example acme/web#31.
• Its branches, and Ready to merge or Can't merge yet with the reason.
• The required checks of its repository.

The monorepo's own required checks must pass too. See Test a change across members in CI.

Review each part on its own pull request page, the same as any pull request. That page shows the notice Part of monorepo pull request, with a link back.

From a terminal, src monorepo pr view 12 shows the parts as a table.

4. Merge all parts#

Click Merge all parts. You need the right to merge in the monorepo and in the repository of each part.

• The button waits until every part can merge. Each part follows the branch rules of its own repository.
• The forge checks every part again before the first one merges. If one part cannot merge, nothing merges, and the message names that part.
• If someone pushed to a part after you opened the page, nothing merges. Reload the page, look at the parts again, and merge.

From a terminal, run src monorepo pr merge 12.

Done#

Every part is merged in its own member. The monorepo pull request shows Merged, and each part shows its merge commit.

If it is partly merged#

The forge merges the parts one at a time, because each part changes its own repository. A part can fail after other parts merged. For example, GitHub can refuse the merge of a member that syncs with GitHub. The monorepo pull request is then Partly merged.

1. Read the reason. The page lists each part that did not merge, with its error.
2. Fix the cause in that part.
3. Click Retry the merge, or run src monorepo pr retry 12.

The parts that merged stay merged. The retry merges only the other parts.

Let an agent open it#

An agent with a session on the monorepo can open a monorepo pull request. Only a person merges it. The forge refuses a merge or a retry from an agent.

1. The agent pushes a branch to each member that it changes. A session pushes only to agent/<session>/... branches.
2. The agent calls the MCP tool create_monorepo_pull, with one part for each folder:

{
  "owner": "acme",
  "repo": "platform",
  "title": "Add the field",
  "body": "The API gets the field, and the docs explain it.",
  "parts": [
    { "folder": "web", "head": "agent/3f9c2a1b7d4e6f80/add-field", "title": "Add the field to the API" },
    { "folder": "docs", "head": "agent/3f9c2a1b7d4e6f80/add-field", "title": "Document the field" }
  ]
}

3. You review and merge it, as in steps 3 and 4.

The agent can use these tools and routes:

What	MCP tool	REST route
Open one	create_monorepo_pull	POST /api/v1/repos/acme/platform/monorepo-pulls
Read one, with each part	get_monorepo_pull	GET /api/v1/repos/acme/platform/monorepo-pulls/12
List them	list_monorepo_pulls	GET /api/v1/repos/acme/platform/monorepo-pulls
Add an open pull request as a part	add_monorepo_part	POST /api/v1/repos/acme/platform/monorepo-pulls/12/parts
Close one	close_monorepo_pull	PATCH /api/v1/repos/acme/platform/monorepo-pulls/12 with {"state": "closed"}

The tools for people only are merge_monorepo_pull (PUT .../monorepo-pulls/12/merge) and retry_monorepo_merge (POST .../monorepo-pulls/12/retry).

Who sees a part#

A private monorepo can have private members. See Who can see a monorepo.

• A person who sees the monorepo can read each private member, so they see every part.
• On the pull request page of a part, only people who can read the monorepo see the notice Part of monorepo pull request. Other people see a normal pull request. They do not learn the name of the monorepo or of the other parts.
• A part whose repository you cannot read shows only as a part you can't see, with no name.

Later: add a pull request that is open already#

You opened a pull request in acme/billing before the monorepo pull request. Add it as a part:

src monorepo pr add-part 12 --repository acme/billing --pull 7

• The pull request must be open, and its branch must be in its own repository, not in a fork.
• A pull request can be a part of one monorepo pull request only.
• The author of the monorepo pull request, or a person who can merge in the monorepo, adds parts.

Later: close it#

Click Close on its page, or run src monorepo pr close 12. Its author, or a person who can merge in the monorepo, closes it.

The parts stay open as normal pull requests. You cannot open the monorepo pull request again.

If a part fails to open#

src monorepo pr create stops at the first part that it cannot open. The message gives the reason. It also names the parts that it opened before, which stay open as normal pull requests.

1. Close those pull requests.
2. Fix the cause.
3. Run src monorepo pr create again.