Pull requests
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). 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
Section titled “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.
Views, search and filters
Section titled “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
Section titled “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).
- 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).
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
Section titled “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, then This project, then 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
Section titled “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
Section titled “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. 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).
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: in Pull request mode it can go to the agent, to the pull request, or Both.
Review threads
Section titled “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
Section titled “What By Dawn does with a pull request”Opening it
Section titled “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
Section titled “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, 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
Section titled “Landing it”What happens next is up to the ticket’s mission. 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).
Merge from By Dawn
Section titled “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, then Organization, then 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.
Does a new review comment on GitHub wake the agent?
No. To hand the agent a review comment, send it a line comment 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 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.
- Changes and the code view: read a ticket’s changes and comment on lines.
- Missions and templates: the steps that take a pull request from green to merged.
- Branching and CI: make By Dawn’s branches fit your CI.
- Test results: the pull request’s Tests tab, and the failing tests a worker gets.