Repository files navigation

Automatically label new pull requests based on the paths of files being changed or the branch name.

• Upgraded action from node20 to node24.

  Make sure your runner is on version v2.327.1 or later to ensure compatibility with this release.Release Notes

For more details, see the full release notes on therelease page

1. The ability to apply labels based on the names of base and/or head branches was added (#186 and#54). The match object for changed files was expanded with new combinations in order to make it more intuitive and flexible (#423 and#101). As a result, the configuration file structure was significantly redesigned and is not compatible with the structure of the previous version. Please read the documentation below to find out how to adapt your configuration files for use with the new action version.

2. The bug related to thesync-labels input was fixed (#112). Now the input value is read correctly.

3. By default,dot input is set totrue. Now, paths starting with a dot (e.g..github) are matched by default.

4. Version 5 of this action updated theruntime to Node.js 20. All scripts are now run with Node.js 20 instead of Node.js 16 and are affected by any breaking changes between Node.js 16 and 20.

Create a.github/labeler.yml file with a list of labels and config options to match and apply the label.

The key is the name of the label in your repository that you want to add (eg: "merge conflict", "needs-updating") and the value is a match object.

The match object allows control over the matching options. You can specify the label to be applied based on the files that have changed or the name of either the base branch or the head branch. For the changed files options you provide apath glob, and for the branches you provide a regexp to match against the branch name.

The base match object is defined as:

-changed-files:   -any-glob-to-any-file:['list', 'of', 'globs']  -any-glob-to-all-files:['list', 'of', 'globs']  -all-globs-to-any-file:['list', 'of', 'globs']  -all-globs-to-all-files:['list', 'of', 'globs']-base-branch:['list', 'of', 'regexps']-head-branch:['list', 'of', 'regexps']

There are two top-level keys,any andall, which both accept the same configuration options:

-any:  -changed-files:    -any-glob-to-any-file:['list', 'of', 'globs']    -any-glob-to-all-files:['list', 'of', 'globs']    -all-globs-to-any-file:['list', 'of', 'globs']    -all-globs-to-all-files:['list', 'of', 'globs']  -base-branch:['list', 'of', 'regexps']  -head-branch:['list', 'of', 'regexps']-all:  -changed-files:    -any-glob-to-any-file:['list', 'of', 'globs']    -any-glob-to-all-files:['list', 'of', 'globs']    -all-globs-to-any-file:['list', 'of', 'globs']    -all-globs-to-all-files:['list', 'of', 'globs']  -base-branch:['list', 'of', 'regexps']  -head-branch:['list', 'of', 'regexps']

From a boolean logic perspective, top-level match objects, and options withinall areAND-ed together and individual match rules within theany object areOR-ed.

One or all fields can be provided for fine-grained matching.The fields are defined as follows:

• all: ALL of the provided options must match for the label to be applied
• any: if ANY of the provided options match then the label will be applied
  • base-branch: match regexps against the base branch name
  • head-branch: match regexps against the head branch name
  • changed-files: match glob patterns against the changed paths
    • any-glob-to-any-file: ANY glob must match against ANY changed file
    • any-glob-to-all-files: ANY glob must match against ALL changed files
    • all-globs-to-any-file: ALL globs must match against ANY changed file
    • all-globs-to-all-files: ALL globs must match against ALL changed files

If a base option is provided without a top-level key, then it will default toany. More specifically, the following two configurations are equivalent:

Documentation:-changed-files:  -any-glob-to-any-file:'docs/*'

and

Documentation:-any:  -changed-files:    -any-glob-to-any-file:'docs/*'

If path globs are combined with! negation, you can write complex matching rules. See the examples below for more information.

# Add 'root' label to any root file changes# Quotation marks are required for the leading asteriskroot:-changed-files:  -any-glob-to-any-file:'*'# Add 'AnyChange' label to any changes within the entire repositoryAnyChange:-changed-files:  -any-glob-to-any-file:'**'# Add 'Documentation' label to any changes within 'docs' folder or any subfoldersDocumentation:-changed-files:  -any-glob-to-any-file:docs/**# Add 'Documentation' label to any file changes within 'docs' folderDocumentation:-changed-files:  -any-glob-to-any-file:docs/*# Add 'Documentation' label to any file changes within 'docs' or 'guides' foldersDocumentation:-changed-files:  -any-glob-to-any-file:    -docs/*    -guides/*## Equivalent of the above mentioned configuration using another syntaxDocumentation:-changed-files:  -any-glob-to-any-file:['docs/*', 'guides/*']# Add 'Documentation' label to any change to .md files within the entire repositoryDocumentation:-changed-files:  -any-glob-to-any-file:'**/*.md'# Add 'source' label to any change to src files within the source dir EXCEPT for the docs sub-foldersource:-all:  -changed-files:    -any-glob-to-any-file:'src/**/*'    -all-globs-to-all-files:'!src/docs/*'# Add 'feature' label to any PR where the head branch name starts with `feature` or has a `feature` section in the namefeature: -head-branch:['^feature', 'feature']# Add 'release' label to any PR that is opened against the `main` branchrelease: -base-branch:'main'

Create a workflow (e.g..github/workflows/labeler.yml seeCreating a Workflow file) to utilize the labeler action with content:

name:"Pull Request Labeler"on:-pull_request_targetjobs:labeler:permissions:contents:readpull-requests:writeruns-on:ubuntu-lateststeps:    -uses:actions/labeler@v6

Various inputs are defined inaction.yml to let you configure the labeler:

You might want to use action called@actions/checkout to upload label configuration file onto the runner from the current or any other repositories. See usage example below:

steps:    -uses:actions/checkout@v5# Uploads repository content to the runnerwith:repository:"owner/repositoryName"# The one of the available inputs, visit https://github.com/actions/checkout#readme to find more    -uses:actions/labeler@v6with:configuration-path:'path/to/the/uploaded/configuration/file'

name:"Label Previous Pull Requests"on:schedule:    -cron:"0 1 * * 1"jobs:labeler:permissions:contents:readpull-requests:writeruns-on:ubuntu-lateststeps:# Label PRs 1, 2, and 3    -uses:actions/labeler@v6with:pr-number:|          1          2          3

Note: in normal usage thepr-number input is not required as the action will detect the PR number from the workflow context.

Labeler provides the following outputs:

The following example performs steps based on the output of labeler:

name:"Pull Request Labeler"on:-pull_request_targetjobs:labeler:permissions:contents:readpull-requests:writeruns-on:ubuntu-lateststeps:    -id:label-the-PRuses:actions/labeler@v6          -id:run-frontend-testsif:contains(steps.label-the-PR.outputs.all-labels, 'frontend')run:|        echo "Running frontend tests..."        # Put your commands for running frontend tests here      -id:run-backend-testsif:contains(steps.label-the-PR.outputs.all-labels, 'backend')run:|        echo "Running backend tests..."        # Put your commands for running backend tests here

To successfully add labels to pull requests using the GitHub Labeler Action, specific permissions must be granted based on your use case:

1. Adding Existing Labels:

   • Requires:pull-requests: write
   • Use this if all labels already exist in the repository (i.e., pre-defined in.github/labeler.yml).

2. Creating New Labels:

   • Requires:issues: write
   • This is necessary if the action needs to create labels that do not already exist in the repository.

However, when the action runs on a pull request from a forked repository, GitHub only grants read access tokens forpull_request events, at most. If you encounter anError: HttpError: Resource not accessible by integration, it's likely due to these permission constraints. To resolve this issue, you can modify theon: section of your workflow to usepull_request_target instead ofpull_request (see exampleabove). This change allows the action to have write access, becausepull_request_target alters thecontext of the action and safely grants additional permissions.

There exists a potentially dangerous misuse of thepull_request_target workflow trigger that may lead to malicious PR authors (i.e. attackers) being able to obtain repository write permissions or stealing repository secrets. Hence, it is advisable thatpull_request_target should only be used in workflows that are carefully designed to avoid executing untrusted code and to also ensure that workflows usingpull_request_target limit access to sensitive resources. Refer to theGitHub token permissions documentation for more details about access levels and event contexts.

To ensure the action works correctly, include the following permissions in your workflow file:

permissions:contents:readpull-requests:writeissues:write

If you prefer not to grant theissues: write permission in your workflow, you can manually create all required labels in the repository before the action runs.

Using thepull_request_target event trigger involves several peculiarities related to initial set up of the labeler or updating version of the labeler.

When submitting an initial pull request to a repository using thepull_request_target event, the labeler workflow will not run on that pull request because thepull_request_target execution runs off the base branch instead of the pull request's branch. Unfortunately this means the introduction of the labeler can not be verified during that pull request and it needs to be committed blindly.

When submitting a pull request that includes updates of the labeler action version and associated configuration files, using thepull_request_target event may result in a failed workflow. This is due to the nature ofpull_request_target, which uses the code from the base branch rather than the branch linked to the pull request — so, potentially outdated configuration files may not be compatible with the updated labeler action.

To prevent this issue, you can switch to using thepull_request event temporarily, before merging. This event execution draws from the code within the branch of your pull request, allowing you to verify the new configuration's compatibility with the updated labeler action.

name:"Pull Request Labeler"on:-pull_request

Once you confirm that the updated configuration files function as intended, you can then revert to using thepull_request_target event before merging the pull request. Following this step ensures that your workflow is robust and free from disruptions.

Contributions are welcome! See theContributor's Guide.