Configurable labels based on conditions for pull requests and Issues

Implements an all-in-one GitHub Action that can manage multiple labels for both pull requests and Issues using configurable matching rules.

Updates

The action will strive to maintain backwards compatibility with older configuration versions. It is nevertheless encouraged to update your configuration files to benefit from newer features. Please follow our releases page to stay up to date.

Installing

The action is configured by adding a file .github/labeler.yml. The file contains matching rules expanded in the Configuration section below.

How to trigger action

To trigger the action on events, add a file .github/workflows/main.yml to your repository with these contents:

name: Label PRs

on:
- pull_request
- issues

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: srvaroa/labeler@master
      env:
        GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

Use the on clause to control when to run it.

• To trigger on PR events, use pull_request. to trigger on PR events and run on the merge commit of the PR. Use pull_request_target instead if you prefer to run on the base.
• To trigger on issue events, add issues.

You may combine multiple event triggers.

A final option is to trigger the action periodically using the schedule trigger. For backwards compatibility reasons this will examine all active pull requests and update their labels. If you wish to examine issues as well, you'll need to explicitly add the issues flag in your config file:

version: 1
issues: True
labels:
- label: "WIP"
  title: "^WIP:.*"

Troubleshooting

This action will avoid failing in all cases, so if you're experiencing unexpected behaviour it's worth looking at execution logs. Typical errors are:

• The configuration file is non existent, or invalid yaml.
• Running the action from a fork, as the GITHUB_TOKEN has not enough permissions to label the main repository (issue for solving this)

Configuring matching rules

Configuration can be stored at .github/labeler.yml as a plain list of label matchers, which consist of a label and a set of conditions for each. When all conditions for a label match, then the Action will set the given label. When any condition for a label does not match, then the Action will unset the given label.

All matchers follow this configuration pattern:

<label>: "MyLabel"
<condition_name>: <condition_parameters>
<condition_name>: <condition_parameters>

For example, this .github/labeler.yml contains a single matcher with a single condition:

version: 1
labels:
- label: "WIP"
  title: "^WIP:.*"

A PR or issue with title "WIP: this is work in progress" would be labelled as WIP. If the title changes to "This is done", then the WIP label would be removed.

Each label may combine multiple conditions. The action combines all conditions with an AND operation. That is, the label will be applied if all conditions are satisfied, removed otherwise.

For example, given this .github/labeler.yml:

version: 1
labels:
- label: "WIP"
  title: "^WIP:.*"
  mergeable: false

A pull request with title "WIP: this is work in progress" and not in a mergeable state would be labelled as WIP. If the title changes to "This is done", or it becomes mergeable, then the WIP label would be removed.

If you wish to apply an OR, you may set multiple matchers for the same label. For example:

version: 1
labels:
- label: "WIP"
  title: "^WIP:.*"
- label: "WIP"
  mergeable: false

The WIP label will be set if the title matches ^WIP:.* OR the label is not in a mergeable state.

Append-only mode

The default behaviour of this action includes removing labels that have a rule configured that does not match anymore. For example, given this configuration:

version: 1
labels:
- label: "WIP"
  title: "^WIP:.*"

A PR or issue with title 'WIP: my feature' will get the WIP label.

Now the title changes to My feature the label will get remove. This is because the labeler configuration includes the WIP label, and its rule does not match anymore.

In some cases you would prefer that the action adds labels, but never removes them regardless of the matching status. To achieve this you can enable the appendOnly flag.

version: 1
appendOnly: true
labels:
- label: "WIP"
  title: "^WIP:.*"

With this config, the behaviour changes:

• A PR with title 'WIP: my feature' will get the WIP label.
• When the title changes to My feature, even though the labeler has a rule for the WIP label that does not match, the label will be respected.

Conditions

Below are the conditions currently supported in label matchers. Note that some conditions are only applicable to pull requests.

All conditions evaluate only when they are explicitly added in configuration (that is, there are no default values).

Title

This condition is satisfied when the title matches on the given regex.

title: "^WIP:.*"

Branch (PRs only)

This condition is satisfied when the PR branch matches on the given regex.

branch: "^feature/.*"

Base branch (PRs only)

This condition is satisfied when the PR base branch matches on the given regex.

base-branch: "master"

Body (PRs and Issues)

This condition is satisfied when the body (description) matches on the given regex.

body: "^patch.*"

Files affected (PRs only)

This condition is satisfied when any of the PR files matches on the given regexs.

files: 
- "cmd/.*_tests.go"

Draft status (PRs only)

This condition is satisfied when the PR draft state matches that of the PR.

draft: true

Matches if the PR is a draft.

draft: false

Matches if the PR is not a draft.

Mergeable status (PRs only)

This condition is satisfied when the mergeable state matches that of the PR.

mergeable: true

Will match if the label is mergeable.

mergeable: false

Will match if the label is not mergeable.

Authors (PRs and Issues)

This condition is satisfied when the author of the PR or Issue matches any of the given usernames.

authors: ["serubin"]

Size (PRs only)

This condition is satisfied when the total number of changed lines in the PR is within given thresholds.

The number of changed lines is calculated as the sum of all additions + deletions in the PR.

For example, given this .github/labeler.yml:

- label: "S"
  size-below: 10
- label: "M"
  size-above: 9
  size-below: 100
- label: "L"
  size-above: 100

These would be the labels assigned to some PRs, based on their size as reported by the GitHub API.

PR	additions	deletions	Resulting labels
First example	1	1	S
Second example	5	42	M
Third example	68	148	L