Label manager for PRs and Issues based on configurable conditions
Implements an all-in-one GitHub Action that can manage multiple labels for both Pull Requests and Issues using configurable matching rules. Available conditions:
Thanks to Launchgood for sponsoring this project.
Please consider supporting the project if your organization is finding it useful, you can do this through GitHub Sponsors.
The action is configured by adding a file .github/labeler.yml
. The
file contains matching rules expanded in the Configuration
section
below.
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.
Add GITHUB_API_HOST
to your env variables, it should be in the form
http(s)://[hostname]/
Please consider sponsoring the project if you're using Labeler in your organization!
To trigger the action on events, add a file .github/workflows/main.yml
to your repository:
name: Label PRs
on:
- pull_request
- issues
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: srvaroa/labeler@master
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
Using @master
will run the latest available release. Feel free to pin
this to a specific version from the releases
page.
Use the on
clause
to control when to run it.
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.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:.*"
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 related to non-existing configuration file or invalid yaml.
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.
Adding a negate
property inside the label block will negate the
result of the evaluation of all conditions inside the label. For
example:
version: 1
labels:
- label: "unknown"
negate: True
branch: "(master|hotfix)"
In this case, label unknown
will be set if the branch does NOT match
master
or hotfix
.
The same behaviour occurs with multiple conditions:
version: 1
labels:
- label: "unknown"
negate: True
branch: "master"
title: "(feat).*"
Only PRs that do NOT match one of the two conditions will get the
unknown
label.
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:
WIP
label.My feature
, even though the labeler has a
rule for the WIP
label that does not match, the label will be
respected.Below are the conditions currently supported in label matchers, in alphabetical order. 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).
This condition is satisfied when the author of the PR can merge it. This is implemented by checking if the author is an owner of the repo.
author-can-merge: True
This condition is satisfied when the author of the PR or Issue matches any of the given usernames.
authors: ["serubin"]
This condition is satisfied when the PR base branch matches on the given regex.
base-branch: "master"
This condition is satisfied when the body (description) matches on the given regex.
body: "^patch.*"
This condition is satisfied when the PR branch matches on the given regex.
branch: "^feature/.*"
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.
This condition is satisfied when any of the PR files matches on the given regexs.
files:
- "cmd/.*_tests.go"
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.
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
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 |
You can exclude some files so that their changes are not taken into
account for the overall count. This can be useful for yarn.lock
,
go.sum
and such. Use exclude-files
:
- label: "L"
size:
exclude-files: ["yarn.lock"]
above: 100
This condition will apply the L
label if the diff is above 100 lines,
but NOT taking into account changes in yarn.lock
.
NOTICE the old format for specifying size properties (size-above
and size-below
) has been deprecated. The action will continue
supporting old configs for now, but users are encouraged to migrate to
the new configuration schema.
This condition is satisfied when the title matches on the given regex.
title: "^WIP:.*"