# Pull requests

> Follow every pull request in a project, see which need you, review one inside By Dawn, and know what By Dawn does with a pull request from draft to merge.

This page helps you keep track of the pull requests your agents and your team open, and get each one merged. By the
end you'll know where to find the ones that need you, how to review and merge one without leaving By Dawn, and what By Dawn
does with a pull request on its own.

A worker's code reaches your repo as a **pull request** (PR): one per repo the ticket changes, opened from the
ticket's branch (see [Branching and CI](https://docs.bydawn.com/branching-and-ci/)). By Dawn opens it, keeps an eye on its checks and reviews,
and shows it on the ticket, on the board and on the project's **Pull requests** page.

Pull requests go through GitHub, using By Dawn's GitHub App, or through Azure DevOps. A few parts of reviewing in By Dawn
are GitHub-only for now, and the page says which.

## The Pull requests page

Choose **Pull requests** in the sidebar, or press `⌘9`. The sidebar row counts the open pull requests,
and a dot means at least one needs action. On a phone it's in the workspace menu.

The page lists the project's pull requests on the left, grouped by what they need:

- **Needs action**: an open pull request whose CI is failing (**CI failing**), that conflicts with the branch it opens
  into (**Merge conflict**), or that a reviewer has asked to change (**Changes requested**).
- **Open**: every other draft or open pull request.
- **Merged & closed**: the ones that have finished. In the **Open** view this group shows only the last seven days,
  as **Merged · recent**.

Each row shows the pull request's state (**Draft**, **Open**, **Merged** or **Closed**), its repo and number, its
ticket, its CI (**CI running**, **CI passed**, **CI failing** or **CI blocked**), its review, and what the ticket's
agent is doing: **SAW working**, **Waiting on you**, **Stalled**, **SAW idle**, or **No agent** for a pull request a
person opened.

*[Screenshot: The Pull requests page: the list grouped into Needs action, Open and Merged · recent, and one pull request's overview with its Checks, Reviews, Files changed and Ticket session cards]*

### Views, search and filters

Search at the top of the page to pick a view or narrow the one you're in:

| View | Holds |
| --- | --- |
| **Open** | Draft and open pull requests, plus the ones that finished in the last seven days. Where the page starts. |
| **Needs my review** | Open pull requests that ask you for a review on GitHub. |
| **Needs action** | The **Needs action** group. |
| **Merged** | Every merged or closed pull request. |
| **All pull requests** | Everything. |

Type words to keep only pull requests that mention them, in the title, the branch, the number or the ticket, such
as `auth 1391`. Typing also suggests filters, which turn into chips: **Repo**, **CI**, **Review**, **Session**,
**Needs action**, **Ticket**, **Created** and **Updated**. Click a chip to switch it between **is** and **is not**.
Dates can be typed as words, such as `updated last week`.

**Sort** orders the list by **Last updated** (the default), **Created**, **Merged or closed**, **PR number** or
**Title**. **Display** groups it by **What it needs** (the default), by **Repo**, or not at all. By Dawn remembers your
view while the tab is open.

### One pull request

Pick a pull request to see it on the right. Its header has:

- **Review in SAW**: opens the ticket's diff on this pull request ([below](#review-a-pull-request-in-by-dawn)).
- **Open ticket** and **Open on GitHub** (the same button opens Azure DevOps for an Azure DevOps pull request).
- **Merge**, for an org admin, on an open pull request that isn't a draft ([Merge from By Dawn](#merge-from-by-dawn)).

Under it, four cards sum it up:

- **Checks**: what failed, what's running and what passed. **Re-run** opens the first failing check on GitHub to
  run it again there.
- **Reviews**: who has been asked to review, who has commented, and any threads still open, with their files and
  lines.
- **Files changed**: the first few files, and **View the diff in SAW**.
- **Ticket session**: what the agent is doing, such as "SAW is waiting on you", and the ticket's latest comments.

## On the ticket and the board

A ticket shows its pull requests in its **Pull requests** section, under **Branch**: one row per pull request, with
its state, CI, review and size. Two buttons on each row open it in **Changes** (**Review the diff of PR #N in
Changes**) or on GitHub. The section's heading sums them up, such as "1 of 2 merged · 2 repos".

A project admin can hide this section with **Show pull requests** in
**Settings › This project › Pull requests**. The Pull requests page and the board still show them.

On the board, a card shows a line such as "2 PRs open for review · 1 merged" with its checks. Two of the built-in
views are about pull requests: **Ready to ship** (in review, every open pull request green and mergeable) and
**Stuck** (among others, failing checks).

### Several pull requests on one ticket

A ticket that changes three repos has three pull requests, and one repo can carry more than one, such as a database
migration split out from the feature. When they have to merge in order, each row has a merge step number, and a
pull request waiting on another says **after #N** ("Merge #N first").

## Review a pull request in By Dawn

**Review in SAW**, on the Pull requests page or the ticket, opens the ticket's **Changes** in **Pull request** mode:
the diff exactly as GitHub shows it. Reading a diff, marking files viewed and the keyboard are on [Changes and the
code view](https://docs.bydawn.com/changes-and-code-view/). It needs the ticket's machine to be reachable; when it isn't, use **Open on
GitHub**.

Above the diff, a strip shows the pull request's title, state and review, **Conflicts with** its target branch if it
does, and its checks, such as "1 failing · 5 passed". Click the checks to list every run, with a link to each.
They're read from GitHub while the strip is on screen, and again every 30 seconds while a check is still running. A
ticket with several pull requests has a switcher to move between them.

From the strip you can:

- **Comment**: write a comment and choose **Post comment**, or **Approve** with an optional note. Both post on
  GitHub from By Dawn's app, signed with your name. `⌘+Enter` posts.
- **Ready for review**, on a draft: take it out of draft.
- **Merge**, for an org admin ([below](#merge-from-by-dawn)).

An approval counts on GitHub only when you're an org admin and By Dawn's reviewer app is installed on the repo.
Otherwise By Dawn posts your approval as a comment ("✅ **Approved**") and its message says why. A merged or closed pull
request is read-only.

To comment on particular lines, use a [line comment](https://docs.bydawn.com/changes-and-code-view/#comment-on-a-line): in **Pull request**
mode it can go to the agent, to the pull request, or **Both**.

### Review threads

Review comments left on GitHub show in the diff, under the lines they were left on. Each thread shows who started
it, how many comments it has, and **Outdated** or **Resolved** when they apply, with a link to open it on GitHub.
Resolved threads start folded. Threads the diff can't place, because the lines changed since or aren't shown, are
listed above the diff instead.

Threads are read from GitHub each time, so they're always current. You reply to and resolve them on GitHub.

Review threads, checks and the file list aren't available for Azure DevOps pull requests yet.

## What By Dawn does with a pull request

### Opening it

A worker opens its pull request as a **draft** early, so reviews have somewhere to land. A draft stays a draft until a
person, or the mission's **Mark the PR ready** step, takes it out. That step runs once the worker finishes, before By Dawn
waits for CI, so a repo can skip CI on drafts and run it only when a pull request is ready for review. By Dawn opens at
most one pull request per branch, and when the worker finishes, it fills in the description with a summary of the
work, its checks and its plan.

A pull request a person attached to the ticket is theirs: By Dawn shows it but never updates, readies or merges it.

### Watching CI

When a worker finishes, its ticket waits in **Building** until CI on its pull requests has finished:

- **CI passes**: the card moves to **Review**.
- **CI fails, or the pull request conflicts**: By Dawn brings the worker back with the failure to fix it. If your CI
  sends its [test results](https://docs.bydawn.com/tests/), the worker gets the failing tests themselves. After three tries with no new
  commit, it stops and flags a person.
- **A green pull request goes red in Review**: the card goes back to **Building** and the worker fixes it.
- **No CI reports within 15 minutes**: the card moves on anyway, because the repo may have no CI. A draft is the
  exception: By Dawn never counts a draft whose checks were all skipped, or that has none, as green, so it waits until the
  pull request is marked ready and CI runs.

### Landing it

What happens next is up to the ticket's [mission](https://docs.bydawn.com/missions/). Each of these is a step you tick, and none is ticked to
start with: **Mark the PR ready** (as soon as the worker finishes), **Get CI green**, **Keep it mergeable** (send
conflicts back to the worker), **Your sign-off**, **Approve the PR**, **Merge the PR** and **Move to Done**. With the last few ticked, the card shows
"SAW is shipping it" while By Dawn finishes the job.

When By Dawn merges, it merges only pull requests it opened, in their merge order, and never past branch protection. It
leaves alone a pull request labelled `do-not-merge` or with changes requested. If the repo needs branches to be up to
date, By Dawn updates the branch just before merging, rather than every time the base moves.

Merging doesn't move the card to **Done** by itself: the **Move to Done** step does. When everything on a ticket has
landed and its mission has nothing left to do, the person it's assigned to gets a notification, such as "Its pull
request was merged.".

After a merge, By Dawn deletes the ticket's branch, as set under **Branch cleanup** (see [When the pull request is
done](https://docs.bydawn.com/branching-and-ci/#when-the-pull-request-is-done)).

## Merge from By Dawn

An org admin can merge an open pull request from its page or from the strip in **Changes**. **Merge** asks to
confirm, and offers **Squash and merge** (the default), **Create a merge commit** or **Rebase and merge**. GitHub's
branch protection still applies.

The **Merge button in SAW** setting decides whether merging from By Dawn is allowed at all. It's in
**Settings › Organization › GitHub**, and a project can only make it stricter:

- **Off — merge on GitHub**, where it starts: people merge on GitHub, and By Dawn only opens and updates pull requests.
- **After a human approves**: people can merge from By Dawn once the pull request is approved on GitHub.

## FAQ

**Does a new review comment on GitHub wake the agent?**

No. To hand the agent a review comment, send it a [line comment](https://docs.bydawn.com/changes-and-code-view/#comment-on-a-line) or a
message on the ticket.

**Why did CI fail straight away on a pull request, with a saw:ci-deferred label?**

In a repo that needs branches to be up to date, By Dawn skips CI on a pull request queued behind another, because it
would have to run again anyway. It labels it `saw:ci-deferred` and runs CI once the pull request reaches the front.
**Requires up-to-date branches** on the [Repos](https://docs.bydawn.com/repos/#merging-when-branches-must-be-up-to-date) page controls
this.

**Can I re-run a failed check from By Dawn?**

Not yet. **Re-run** opens the check on GitHub, where you can run it again.

**Does By Dawn work with GitLab merge requests?**

Not yet. By Dawn opens pull requests on GitHub and Azure DevOps.

## Next

- [Changes and the code view](https://docs.bydawn.com/changes-and-code-view/): read a ticket's changes and comment on lines.
- [Missions and templates](https://docs.bydawn.com/missions/): the steps that take a pull request from green to merged.
- [Branching and CI](https://docs.bydawn.com/branching-and-ci/): make By Dawn's branches fit your CI.
- [Test results](https://docs.bydawn.com/tests/): the pull request's **Tests** tab, and the failing tests a worker gets.

Source: https://docs.bydawn.com/pull-requests/