Command Restriction

In some scenarios, you might want to restrict who can use Mergify commands to ensure they’re executed only by authorized individuals. The command restrictions feature allows you to define a set of users or teams who are permitted to use specific Mergify commands.

With command restrictions, you can use conditions to define the valid context that is authorized to run a specific command. This could be a list of allowed users or teams, or even attributes related to the pull request itself.

The restrictions are configured with the top-level key commands_restrictions which can specify restrictions for each command.

To limit backport commands for pull requests coming from the main branch:

commands_restrictions:
  backport:
    conditions:
      - base = main

To limit backport commands usage to a specific team (or user):

commands_restrictions:
  backport:
    conditions:
      - sender = @team

To limit backport commands for users with a specific permission on the repository:

commands_restrictions:
  backport:
    conditions:
      - sender-permission >= write

Every command already has a default restriction, so you only need to configure one when you want something other than the default.

Most commands require sender-permission >= write: only someone who can write to the repository can run them.

update, rebase, squash and refresh are the commands a contributor is expected to run on their own pull request. They also accept the pull request’s own author, but only when the pull request comes from a fork:

conditions:
  - or:
      - sender-permission >= write
      - and:
          - sender = {{author}}
          - from-fork

The fork condition matters because update, rebase and squash all write to the pull request’s head branch: update pushes a merge commit of the base branch onto it, while rebase and squash force-push a rewritten one. On a pull request opened from a fork, that branch lives outside your repository, so writing to it touches nothing you protect. On one opened from a branch of your own repository, the head branch is one of yours. Pushing such a branch takes write permission, but opening a pull request from one that already exists takes only read permission. Without the fork condition, someone with only read permission could open a pull request from one of your branches and have Mergify write to it on their behalf.

refresh writes nothing: it only reevaluates the pull request against your configuration. It carries the same default anyway, so the four commands a contributor reaches for on their own pull request all behave alike.

If you want the author of a same-repository pull request to be able to run these commands too, set the restriction yourself:

commands_restrictions:
  rebase:
    conditions:
      - or:
          - sender-permission >= write
          - sender = {{author}}

To drop a command’s default restriction altogether, set its conditions to true. That’s shorthand for an empty list of conditions. With nothing to check, anyone who can comment on the pull request can run the command:

commands_restrictions:
  refresh:
    conditions: true

conditions:
  - sender-permission >= write

conditions:
  - sender-permission >= write

conditions:
  - sender-permission >= write

conditions:
  - sender-permission >= write

conditions:
  - or:
      - sender-permission >= write
      - and:
          - sender = {{author}}
          - from-fork

conditions:
  - or:
      - sender-permission >= write
      - and:
          - sender = {{author}}
          - from-fork

conditions:
  - sender-permission >= write

conditions:
  - or:
      - sender-permission >= write
      - and:
          - sender = {{author}}
          - from-fork

conditions:
  - or:
      - sender-permission >= write
      - and:
          - sender = {{author}}
          - from-fork