Pull requests

A pull request proposes merging the saved versions on one branch into another, usually main. Your co-authors can look at the changes, comment and approve before anyone merges. This page covers opening, reviewing and merging pull requests, and the project’s merge settings.

Open a pull request

1. Save a version on your branch. Pull requests include saved versions only.
2. Open the project page and click the Pull requests tab.
3. Click New pull request.
4. Choose the branch to merge From and the branch to merge Into (main by default).
5. Give it a Title, and optionally a Description of what changed and why.
6. Click Open pull request.

You can also start a pull request from a branch’s actions menu on the Branches tab, or with Open pull request on the page that compares a branch with main.

Pull requests are numbered within each project, such as #3. Only one pull request can be open for the same pair of branches at a time.

Note

If you see “The source branch has no saved version yet. Save a version on it first.” or “Nothing to merge”, save a version with your changes on the source branch, then try again.

Review a pull request

A pull request page has three tabs:

Tab	What it shows
Conversation	The description, comments and a timeline of what happened.
Files changed	Every change the merge would bring in. Switch between Code diff and PDF to see changed lines or the compiled pages before and after.
Versions	The saved versions on the source branch that the target branch doesn’t have yet.

To comment, type in Leave a comment… on the Conversation tab and click Comment. Comments apply to the whole pull request. You can’t comment on individual lines.

Approve

Owners and editors can click Approve on someone else’s pull request. You can’t approve your own. If a new version is saved on the source branch after you approved, your approval no longer counts towards the requirement. Click Approve again to approve the latest version, or Withdraw approval to take it back.

There is no “request changes” option. Leave a comment instead.

Merge a pull request

The merge box at the bottom of the Conversation tab checks that the pull request is ready:

• No conflicts with main, or a list of files that have conflicts. See Resolve merge conflicts.
• How many of the required approvals it has.
• Whether the target branch has unsaved changes.

When it shows Ready to merge:

1. Click Merge.
2. You see “Merged into main.” People editing the target branch see the changes arrive live.

The merge adds a new version on the target branch called “Merge pull request #N from” followed by the branch name. After merging, the owner can click Delete branch to remove the source branch, unless the project deletes it automatically.

If the target branch has unsaved changes

If someone has changed the target branch since its last saved version, merging replaces those changes. The merge box shows “main has N unsaved changes”. To keep them, ask whoever made them to save a version first. To go ahead and replace them, tick Replace them, then merge.

When merging is blocked

Reason shown	What to do
“Only owners and editors can merge.”	Ask an owner or editor to merge.
“Needs N more approval(s).”	Ask an owner or editor to approve.
“Resolve the conflicts first.”	Click Resolve conflicts.
“Confirm replacing the unsaved changes on main.”	Tick Replace them, or save a version on main first.
“This project is archived.”	The owner must unarchive the project first.

Close or reopen a pull request

To close a pull request without merging, click Close in the merge box, then Close pull request. Nothing is merged.

A closed pull request can be reopened with Reopen while both of its branches still exist. A merged pull request can’t be reopened.

Merge settings

The project owner can control how work reaches main:

1. Open the project’s Settings.
2. Click Branches & merging.
3. Change any of these settings. Each change is saved straight away.

Setting	What it does	Default
Protect main	Only the owner edits main directly. For everyone else, main is read-only: they work on a branch and merge it with a pull request.	Off
Required approvals before merge	How many approvals (0 to 3) a pull request needs before it can be merged. Approvals come from owners and editors, never the pull request’s author, and count only for its latest version.	0
Delete branches after merge	Deletes a pull request’s source branch once it is merged.	Off

When main is protected, editors who open main in the editor see a Protected badge and a notice with a Create a branch button.

Note

Protect main stops other people from editing main directly. Editors can still merge approved pull requests into it.

Who can do what

Action	Owner	Editor	Viewer
Read pull requests and comment	Yes	Yes	Yes
Open, close and reopen	Yes	Yes	No
Approve (not your own)	Yes	Yes	No
Merge	Yes	Yes	No
Edit the title and description	Owner, or the pull request’s author
Change merge settings	Yes	No	No

Notifications

Owners and editors get an in-app notification when someone opens a pull request. The author is notified when their pull request is approved, commented on, merged or closed. Pull requests don’t send email. See Notifications.

Limits

Item	Limit
Title	255 characters
Description	20,000 characters
Comment	10,000 characters

Related

• Branches
• Resolve merge conflicts
• Roles and permissions