Rebasing Pull Requests

Rebasing is a method to integrate changes from one branch into another. It’s essentially like “replaying” changes from your branch onto another branch. This is helpful when you want to ensure your changes are built upon the most recent commits of the branch you’re targeting.

Rebasing a pull request in GitHub allows you to update the entire commit history of a branch onto its base branch, while the base branch received new commits.

Mergify allows to rebase pull requests in two different ways:

• Either by using the rebase command which rebases the pull request immediately;

• Either by using an automation rule that automatically triggers a rebase when a pull request meets conditions.

To instantly rebase a pull request without leaving GitHub, use the Mergify rebase command by typing:

@mergifyio rebase

This command triggers a git rebase operation and force-push the rebased branch.

The rebase command provided by Mergify has several advantages over the native GitHub rebase feature:

• Rebases are done using the --autosquash option. This mean commits starting with fixup!, squash! or other commands will be honored.

• When the dismiss_reviews action is being used, it will not reset the reviews if the rebase is executed by Mergify.

• It’s always available, whatever the repository configuration might be.

• It can be restricted to certain users or teams.

You might be tempted to rebase pull requests automatically when they are behind their base branch, such as main or master. The rebase action is a great candidate to help in such a case.

You can write an automation rule that does exactly this for you:

pull_request_rules:
  - name: continuously rebase pull requests when it's labeled with `rebase`
    conditions:
      - label = rebase
    actions:
      rebase:

Note that this rebases the pull request as long as it has the label.

If you wanted to rebase only once, you would also need to remove the label once the rebase is done:

pull_request_rules:
  - name: rebase pull requests once when it's labeled with `rebase`
    conditions:
      - label = rebase
    actions:
      rebase: {}
      label:
        remove:
          - rebase

As rebasing a PR is likely to re-trigger your CI, rebasing your PR continuously could be time consuming for your CI system. Rather than doing it on every merge done in the base branch, you can rebase only when the PR is behind a number of commits. For example:

pull_request_rules:
  - name: rebase pull request when it's more than 10 commits behind main
    conditions:
      - base = main
      - "#commits-behind >= 10"
    actions:
      rebase:

With this rule, as soon as the pull request is more than 10 commits behind the main branch, Mergify automatically rebases the pull request which therefore retriggers the CI. This is useful to make sure that you don’t merge pull request that are too much out-of-date.

As stated above, rebasing too often your pull requests might not be great for your CI resource usage. Therefore, you could also use a strategy where rebase would only be done during a certain time frame, once a day.

pull_request_rules:
  - name: rebase pull requests in the morning
    conditions:
      - base = main
      - "schedule = Mon-Fri 08:00-09:00[US/Pacific]"
    actions:
      rebase:

With this rule, any pull request that is out-of-date between 8am and 9am PST during the week will be rebased.