Automatically merge verified and tested GitHub Pull Requests

Question

I'd like to automatically (i.e. from Jenkins) merge a GitHub pull request that has been approved by a person and has been tested successfully; in other words, when all THREE of these checkmarks are green:

Is this possible? I haven't found any documentation on an API for GitHub's new "changes approved" code review functionality.

Misgovern

Thanks to @kfb's answer, I've written a NodeJS script to do this: listen to GitHub and auto merge when ready. – Misgovern

This is now (Feb. 2021) officially available: See my answer below. – Enrica

Answer 1

There is a new PullRequestReviewEvent webhook that is triggered when a review is submitted in a non-pending state. The body of the webhook contains the ["review"]["state"] field, which will be approved when all reviewers have approved the changes (i.e. when you get the green "changes approved" tick in the UI).

Combine this with the StatusEvent for the head SHA of your pull request to get the status checks from CI and so on, then finally check the "merge-ability" of the pull by requesting the pull request from the API:

GET /repos/:owner/:repo/pulls/:number

Once you have all three things, you can merge the pull request with:

PUT /repos/:owner/:repo/pulls/:number/merge

and appropriate payload parameters. Note you'll need the Accept: application/vnd.github.polaris-preview+json for some of the payload parameters as they are in a preview period.

Ornithopod

Is this possible to achieve this via straightforward API calls ? I want to create a cli program that takes args like repo-name ,pr-id that could check for the status of a PR and merge it based on a status from the api response rather than relying on a event based hook – Scrutator

You can read the events using the Issue Timeline API, though I've not used this API myself so can't give any specific advice on how to achieve what you're after. – Ornithopod

i set up a nodejs server to listen to hook based events but i get approved state even though one of the reviewer has selected CHANGES_REQUESTED . Any clue why ? – Scrutator

No idea, sorry! – Ornithopod

Answer 2

Official documentation: "Managing auto-merge for pull requests in your repository".

---

That is now (Dec. 2020, 4 years later) available:

Pull request auto-merge public beta

Pull request auto-merge is now rolling out as a public beta!

With auto-merge, pull requests can be automatically merged when all requirements for merging are met. No more waiting for long checks to finish just so you can press the merge button!

To use auto-merge, a repository maintainer or admin must first toggle on the repository setting to allow auto-merge (see steps).
Then any user with write permission can enable or disable auto-merge by navigating to the pull request page.

Keep in mind that auto-merge is only available for pull requests targeting a branch with required reviews or required status checks, and therefore is only available on public repositories and private repositories on Team and GitHub Enterprise Cloud plans.

Learn more about pull request auto-merge.

---

Update Feb. 2021:

Pull request auto-merge is now generally available

With auto-merge, pull requests can be set to merge automatically when all merge requirements are met.
No more waiting on slow CI jobs or tests to finish just so you can click the merge button!

To use auto-merge, first have an administrator allow auto-merge in the repository settings.

Then to enable auto-merge, navigate to the pull request on GitHub.com or GitHub Mobile and tap the button to enable.

Note that auto-merge can only be enabled by users with permission to merge and when there are unsatisfied merge requirements, like missing approvals or failing required status checks.

GraphQL APIs will be rolling out later this week. The pull request webhook event also now includes actions that indicate when auto-merge is enabled or disabled.

Learn more about pull request auto-merge

---

However, as The Godfather mentions in the comments:

The problem with this is that it doesn't do auto-update.

So as soon as your repo has "branches must be up-to-date" and some other PR got merged, this "auto-merge" doesn't work any more.

It should have been called the same way as Gitlab: "merge when pipeline succeeds", at least it's not as confusing... –

---

Update Aug. 2021:

Maintainers can now manage the availability of auto-merge in a repository

Maintainers can now manage the repository-level "Allow auto-merge" setting.
This setting, which is off by default, controls whether auto-merge is available on pull requests in the repository.
Previously, only admins could manage this setting.

Additionally, this setting can now by controlled using the "Create a repository" and "Update a repository" REST APIs.

Enrica

@Misgovern This should be selected as the correct answer. – Daph

The OP asked for "when all THREE of these checkmarks are green". Github's feature merges when only the required checks have passed and others are still running, when the checks are still yellow. The app I wrote and introduced in my answer does what the OP wants though. 😎 – Acquittal

The problem with this is that it doesn't do auto-update. So as soon as your repo has "branches must be up-to-date" and some other PR got merged, this "auto-merge" doesn't work any more. It should have been called the same way as Gitlab: "merge when pipeline succeeds", at least it's not as confusing... – Passageway

@TheGodfather Good point. Thank you for this feedback. I have included your comment in the answer for more visibility. – Enrica

Answer 3

I wrote an app that does this. It responds to the review, labelled, and commit status/checks events, and merges when the merge button is green.

The fact that it merges when the merge button is green means that you can configure the requirements for a mergeable PR in the GitHub settings, there's no need to write separate configuration for the app.

Mergery is:

• Free, including for private repositories.
• Fast. It's event-driven, it doesn't run on a schedule.
• Simple. No configuration required. Just label your PRs with automerge.

Acquittal

Answer 4

You can use Mergify to do exactly this, since this is what it has been created for. Just set up a minimal .mergify.yml file in your repository:

rules:
  default:
    protection:
      required_status_checks:
        context:
          - continuous-integration/travis/pr
      required_pull_request_reviews:
        required_approving_review_count: 1

And you'll be good to go.

(disclaimer: I'm one of the Mergify founders)

Overnice

Answer 5

Using github actions which is one of the new ways, this can be done. I have written a blog about auto approving and auto merging PRs using github actions. However, if the intent is to just merge the PRs only, then then the second job in this work flow would be enough to do it.

Agenda

Answer 6

https://github.com/bobvanderlinden/probot-auto-merge is a free GitHub app that does the job. It's configurable in .github/auto-merge.yml.

Enos