Selecting your Bot Account

Selecting your Bot Account

Julien Danjou

New Mergify users might wonder what hides behind this cryptic title. Do not fear: I am sure you're going to like it.

Before jumping into the feature presentation — which ought to be short as it's a simple variable in your configuration — you need to understand the problem.

The Problem

Mergify is a GitHub Application. That means it has a special status on GitHub and is not a regular GitHub user. It can act on behalf of users and organizations that authorized it to do so.

Its power is limited to the granted authorization it has received from those users, but it is also limited by what GitHub thinks an application should be able to do.

In Mergify's case, this is a problem because there are some actions that we would like to execute for you, but GitHub does not think a GitHub application should be able to run them.

We're pretty sad about this, GitHub.

To give you an example, one of the actions Mergify is not allowed to execute on behalf of an organization is pushing the branch in a pull request. This is a problem when you ask Mergify to rebase a pull request on top of its base branch: it has to then force-push the rebased branch.

The Solution

Early on, we found a pretty good workaround to this limitation: rather than doing this as an application, we would do it as a user. Since Mergify's dashboard required an OAuth token to be accessed, this token could be used to impersonate a user and, e.g., to push a branch.

This is why if you use the merge action option strict_method: rebase you might see one user from your organization doing the rebase, while it is Mergify acting behind the scene.

Until now, Mergify did not care about which user would be used to execute the action, as long as its token was valid. It would select a user randomly and use the first one that worked.


We added a new option to the merge and rebase actions named bot_account. This option allows you to select the GitHub user that Mergify impersonates when it needs to step out of its application limitations.

  1. Create a GitHub user and add it to your organization with the correct write permissions to the repository.
  2. Log this user in the Mergify dashboard so Mergify can get an OAuth token.
  3. Set the bot_account option in your merge or rebase action configuration.
  4. You will now see the correct user account being used to, e.g., rebase your pull requests.
  - name: automatic merge
      - "status-success=ci/circleci: test"
      - "#approved-reviews-by>=1"
        strict: smart
        method: merge
        strict_method: rebase
        bot_account: myorg-bot
Example using the bot_account option

Ultimately, we all wish that GitHub would extend the permissions that a GitHub Application would receive when granted write access to a repository. 🤞Unfortunately, we had little success so far!