Update

The update action instructs Mergify to update the pull request branch with its base branch.

When this action is added to a rule, Mergify will update the pull request branch with the latest changes from its base branch, if necessary. This is done by merging the base branch into the pull request branch.

Whatever your conditions are, Mergify adds its own requirements before running the action. A pull request is updated only when it is open, has no conflict, is not in a merge queue (queue-position = -1), and is behind its base branch (#commits-behind > 0).

This action writes the pull request’s head branch. On a pull request opened from another repository, Mergify writes that branch only when it belongs to your repository or to a fork of it, and reports why on the pull request when it does not. A queue that uses in-place checks writes that branch too, and runs the same check when a pull request asks to be queued, so such a pull request is refused when it enters the queue rather than dequeued later.

That comparison can only refuse a write when your own repository is itself a fork: any other repository is the root of its own fork network, so every head it sees descends from it. On a fork, Mergify refuses a head branch that lives in the repository yours was forked from, in a sibling fork, or in a fork more than one level below yours, since it compares only the head repository’s immediate parent and the root of its fork network. It also refuses a head branch in a repository it cannot read, such as a private fork outside your Mergify installation.

A head branch whose repository has been deleted is refused on any repository, fork or not, since nothing is left to say which repository that branch belongs to.

You can ask Mergify to update your pull requests when they are a few commits behind their base branch, for example:

pull_request_rules:
  - name: automatic update of pull requests that are more than 5 commits behind
    conditions:
      - base = main
      - "#commits-behind > 5"
    actions:
      update:

As GitHub supports linear history in pull request settings, it is very handy to use a rule to keep your pull requests up-to-date. As you do not want to trigger your CI too often by always re-running it on every pull request (especially when there is still work in progress), you can limit this action to labeled pull requests.

pull_request_rules:
  - name: automatic update for pull requests marked as "keep-up-to-date"
    conditions:
      - -draft # filter-out draft PRs
      - label = keep-up-to-date
    actions:
      update:

When a pull request is not a draft, and has the label keep-up-to-date, it will be automatically updated with its base branch.