---
title: Update
description: Update the pull request branch with its base branch.
---

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

<Image src={updateBranchScreenshot} alt="Mergify Branch Update" />

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.

:::note
  You do not need to use this action if you use the [merge
  queue](/merge-queue). The merge queue automatically updates the pull requests
  it processes as necessary, making sure they are tested with up-to-date code
  before being merged.
:::

## Update Requirements

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`](/configuration/conditions#attributes-list)), and is
behind its base branch (`#commits-behind > 0`).

## Fork Pull Requests

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](/merge-queue/batches#in-place-checks-no-batch-prs) 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.

The update action checks one more thing, and checks it before any of the above.
When your repository is public, Mergify refuses to update a pull request from a
fork whose author has not ticked GitHub's ["Allow edits from
maintainers"](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)
box, and the check run asks them to tick it. The box is not required when your
repository is private. A queue using in-place checks requires it whatever the
visibility, when a pull request asks to be queued.

## Parameters

| Key name | Value type | Default | Description |
| --- | --- | --- | --- |
| `bot_account` | simple-template or null | `null` | Mergify can impersonate a GitHub user to update a pull request. If no `bot_account` is set, Mergify will update the pull request itself. |

## Examples

### Update When Behind

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

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

### Linear History

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.

```yaml
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.