Get pull requests merged

When the agent finishes its work it opens a pull request on your code host. A session isn’t done at that point. Evergreen’s shepherd keeps watching the pull request, fixes what breaks and, if you let it, merges it. This page covers how many pull requests a session opens, how far the shepherd goes, and how you steer it.

One pull request or several

Most sessions open one pull request. For a bigger change, the agent can split the work into several in its plan, each on its own branch and each possibly in a different repository. You approve the split when you approve the plan.

The Pull requests section of the session’s Overview lists them, with a progress line such as 2 of 6 merged. While some are still open, choose the progress line to show the ones that already merged or closed. They merge from top to bottom. Each step waits for the step above it to merge, and pull requests in the same step can merge in any order. Choose How merge order works to read the rules in the app.

• A pull request that depends on another stays a draft so it can’t merge early. Evergreen marks it ready once the one it depends on has merged and the agent’s turn is over.
• A stacked pull request is built on another pull request’s branch. When the lower one merges, Evergreen moves the stacked one onto the base branch.
• If you chose Ask before every fix, or you took over, drafts stay drafts until someone marks them ready.

How far Evergreen goes

The Shepherd section of the Overview shows the mode in a button. You can also choose it before you start, under Once the PR is open. The three modes are:

In Ask before every fix, a card asks before each follow-up, naming the failing check or the reviewer’s comment. Fix it lets the agent go ahead, and Not now holds it back. A session set to Carries on without you doesn’t stop for these cards.

A project can set its own Default merge policy under its Setup tab. When a session has more than one repository and is on Auto merge when green, Per repo in the mode menu lets each repository either merge on green (Auto) or wait for your approval (I approve).

What counts as green

Green means the required checks and the testing level you chose have passed, and no reviewer’s latest word is “changes requested”. An automated reviewer’s approval clears its own request for changes, but only a person’s approval counts as approved. Your code host still has the last word, so a branch protection rule can hold a merge that Evergreen would allow.

What the shepherd does

Choose How the shepherd works in the mode button’s menu for the full explanation. In short:

• It watches the pull request. A failing required check, a review, or a merge conflict becomes a short follow-up run on the same conversation, or a card asking you first, depending on the mode. Nothing merges while a run is working or a card is open.
• It reads each review before acting. Concrete requests become the agent’s brief. A review that asks for a judgment call, such as scope, product, or security, or one that says nothing at all, goes to a person.
• It answers each review, replies on the pull request, and asks the reviewers who requested changes to look again.
• It has a limit on attempts. When the limit is reached, it stops and asks for a person.

Testing before merge

The shepherd always waits for the repository’s required checks. In the Shepherd section, Testing adds a level on top of them.

When you start a session, the same choice is called Before it merges, also require, with the answers Nothing extra, Tests, and CI. In Auto merge when green, the merge waits for the level to pass. In the other two modes your approval doesn’t wait for it. A project can set Minimum validation, a floor that sessions in it can’t go below. You can raise or lower the level later, down to that floor.

After merge, in the same section, asks the agent to check what happens next. Nothing after merge ends the work at the merge. CI passes on the base branch also watches CI on the merge commit. Deployed successfully adds a check that the deploy reaches every environment on its route. Monitoring looks good compares production data in Datadog before and after the deploy. If one of these checks fails, the session continues on fresh branches to fix it forward, and the fix’s own merge is checked again.

When a merge is held up

A line under the pull requests says why a merge is waiting. These are the common ones.

When a failure isn’t the pull request’s own, such as a red base branch or flaky tests, the session can offer a card titled Fix this outside the pull request. Fix it once starts a session of your own to fix the cause, and Not now leaves it. When the base branch is red and you have automations, Set up self-healing comes first: it creates an automation that fixes this red now and every later one on that branch, so the card doesn’t come back. Only a person answers this card, even in a session that carries on without you. If another session is already fixing the same thing, the session names that one instead of offering a card.

Take the wheel

A pull request’s menu and the session offer these actions when they apply to it.