Label

Add, remove, or toggle labels on a pull request.

The label action allows Mergify to automatically add or remove labels from a pull request based on the conditions specified in your rules.

A label named in add or toggle that does not exist in the repository yet is created with a randomly picked color. Create it yourself first if you want to choose its color and description. Mergify only adds labels the pull request does not already carry, and only removes ones it does, so a rule whose conditions keep matching does not keep calling GitHub.

GitHub caps a pull request at 100 labels, and refuses a request that would go past the cap, rather than adding the labels that fit. A rule asking for more labels than there is room for adds none of them: Mergify reports that there is no room and names the labels it could not add. Free up room and Mergify adds them on the next evaluation.

Avoid rule pairs that flip the same label. If one rule adds a label and another removes it, and both rules’ conditions keep matching after each flip, the two rules keep undoing each other, because every change re-triggers rule evaluation.

Mergify stops such a loop instead of letting it run. A change counts toward the stop only when it reverses Mergify’s own previous change of that label and comes from a different rule. Once a label would be reversed for the tenth time within an hour, Mergify stops changing it on that pull request in either direction. The action then reports a failure naming the label and the rules that were undoing each other, and leaves the label as it is. Mergify changes that label again once the repository’s Mergify configuration changes.

Do not rely on the stop. Scope your conditions so they become mutually exclusive once the label is applied. For example, guard post-merge cleanup rules with the merged condition and drop that label from any opposing rule’s conditions.

Parameters

addlist of string#

The list of labels to add.

removelist of string#

The list of labels to remove.

remove_allboolean·defaultfalse#

Remove all labels from the pull request.

togglelist of string#

Toggle labels in the list based on the conditions. If all the conditions are a success, all the labels in the list will be added, otherwise, they will all be removed.

Examples

WIP

pull_request_rules:
  - name: add "WIP" label when the title contains "WIP"
    conditions:
      - title ~= WIP
    actions:
      label:
        toggle:
          - WIP

In this example, Mergify will automatically add the “WIP” label to any pull request whose title contains “WIP”. If the pull request does not match the rule anymore, the label will be removed.

Warn on conflicts

When browsing the list of pull requests, GitHub does not give any indication on which pull requests might be in conflict. Mergify lets you do this by adding a label.

pull_request_rules:
  - name: warn on conflicts
    conditions:
      - conflict
    actions:
      comment:
        message: "@{{author}} this pull request is now in conflict 😩"
      label:
        toggle:
          - conflict

Then, your pull request list will look like this on conflict:

Pull request in conflict in pull request list

Toggle a label based on CI status

This rule toggles a label based on the failure status of a CI system.

pull_request_rules:
  - name: toggle labels based on CI state
    conditions:
      - check-failure = CI
    actions:
      label:
        toggle:
          - "CI:fail"

Add a label based on the target branch

This rule adds a static label to pull requests targeting a given branch.

pull_request_rules:
  - name: label pull requests targeting the release branch
    conditions:
      - base = release
    actions:
      label:
        add:
          - "release"

Was this page helpful?