---
title: Label
description: Add, remove and 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, making your
workflow more organized and efficient.

:::caution
  **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 label toggles back and forth indefinitely. Every change
  re-triggers rule evaluation. 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.
:::

:::caution
  **Avoid using labels to trigger CI workflows.** GitHub Actions workflows
  subscribed to `labeled` or `unlabeled` pull request events run on every
  label change. Coupling CI to label state makes runs sensitive to any actor
  that touches labels (people or automation) and can amplify the cost of a
  misbehaving rule into redundant workflow runs on a single pull request.
  Trigger CI from code events such as `push` or `pull_request` and reserve
  labels for state and visibility.
:::

## Parameters

| Key name | Value type | Default | Description |
| --- | --- | --- | --- |
| `add` | list of template |  | The list of labels to add. |
| `remove` | list of template |  | The list of labels to remove. |
| `remove_all` | boolean | `false` | Remove all labels from the pull request. |
| `toggle` | list of template |  | 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

```yaml
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 request, GitHub does not give any indication on
which pull requests might be in conflict. Mergify allows to do this easily by
adding a label.

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

<Image src={prConflictScreenshot} alt="Pull request in conflict in pull request list" />

### Toggle A Label Based on CI Status

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

```yaml
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 Name of The Branch

This rule add a label with the name of the branch.

```yaml
pull_request_rules:
  - name: add a label with the name of the branch
    conditions: []
    actions:
      label:
        add:
          - "branch:{{base}}"
```