Pull Request Labeler

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

Breaking changes in V6

• 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 the release page

Breaking changes in V5

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 the sync-labels input was fixed (#112). Now the input value is read correctly.

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

4) Version 5 of this action updated the runtime 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.

[!IMPORTANT] Before the update to the v5, please check out this information about the pull_request_target event trigger.

Usage

Create .github/labeler.yml

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.

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 a path 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 and all, 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 within all are AND-ed together and individual match rules within the any object are OR-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 to any. 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.

Basic Examples

# Add 'root' label to any root file changes
# Quotation marks are required for the leading asterisk
root:
- changed-files:
  - any-glob-to-any-file: '*'

# Add 'AnyChange' label to any changes within the entire repository
AnyChange:
- changed-files:
  - any-glob-to-any-file: '**'

# Add 'Documentation' label to any changes within 'docs' folder or any subfolders
Documentation:
- changed-files:
  - any-glob-to-any-file: docs/**

# Add 'Documentation' label to any file changes within 'docs' folder
Documentation:
- changed-files:
  - any-glob-to-any-file: docs/*

# Add 'Documentation' label to any file changes within 'docs' or 'guides' folders
Documentation:
- changed-files:
  - any-glob-to-any-file:
    - docs/*
    - guides/*

## Equivalent of the above mentioned configuration using another syntax
Documentation:
- changed-files:
  - any-glob-to-any-file: ['docs/*', 'guides/*']

# Add 'Documentation' label to any change to .md files within the entire repository
Documentation:
- 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-folder
source:
- 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 name
feature:
 - head-branch: ['^feature', 'feature']

# Add 'release' label to any PR that is opened against the `main` branch
release:
 - base-branch: 'main'

Configuration Options

The labeler configuration file (.github/labeler.yml) supports the following top-level options:

Name	Description
changed-files-labels-limit	Maximum number of new labels to apply based on changed files (must be a non-negative integer). If exceeded, no changed-files labels are applied for that run.
max-files-changed	Maximum number of total changed files (must be a non-negative integer). If exceeded, all file-based labeling is skipped.

Limiting changed-files labels

When working with large PRs (e.g., tree-wide refactors) that touch many components, you may want to prevent the labeler from adding too many labels. Set changed-files-labels-limit in your .github/labeler.yml configuration file to limit the number of labels that can be applied based on changed files patterns.

Important behaviors:

• The limit counts only new labels that would be added by changed-files rules. Labels already present on the PR are not counted toward the limit.
• If the number of new changed-files labels exceeds the limit, all new changed-files labels are skipped for that run.
• If the number of new changed-files labels equals the limit, labels are still applied normally.
• Labels based on branch conditions (head-branch, base-branch) are not affected by the limit.
• Any label definition that includes a changed-files rule is considered a changed-files label and is subject to the limit, regardless of which condition caused the label to match. For example, a label with both head-branch and changed-files rules will be subject to the limit even if it matches via the branch rule.
• If both max-files-changed and changed-files-labels-limit are configured at the same time, max-files-changed is evaluated first, and if it triggers, changed-files-labels-limit is not evaluated.

Example

# .github/labeler.yml

# Limit changed-files based labels to 5
changed-files-labels-limit: 5

# Label definitions - these are subject to the limit
frontend:
  - changed-files:
    - any-glob-to-any-file: 'src/frontend/**'

backend:
  - changed-files:
    - any-glob-to-any-file: 'src/backend/**'

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

# This label has both branch and changed-files rules.
# It is still subject to the limit because it includes changed-files.
mixed:
  - any:
    - head-branch: '^feature/'
    - changed-files:
      - any-glob-to-any-file: 'src/mixed/**'

# Branch-based labels are NOT affected by the limit
feature:
  - head-branch: '^feature/'

Skipping labeling for large PRs

When a PR modifies a very large number of files (e.g., tree-wide refactors, automated code formatting), you may want to skip file-based labeling entirely. Set max-files-changed in your .github/labeler.yml configuration file to skip all file-based labeling when the total number of changed files exceeds the threshold.

Important behaviors:

• If the total number of changed files exceeds the limit, all file-based labeling is skipped entirely.
• If the total number of changed files equals the limit, labels are still applied normally.
• Labels based only on branch conditions (head-branch, base-branch) are not affected by the limit.
• Any label definition that includes a changed-files rule is considered a file-based label and will be skipped, regardless of which condition caused the label to match. For example, a label with both head-branch and changed-files rules will be skipped even if it would match via the branch rule.
• Pre-existing labels on the PR are preserved — changed-files configs are not evaluated at all, so sync-labels will not remove them.

Example

# .github/labeler.yml

# Skip file-based labeling if more than 100 files changed
max-files-changed: 100

# These labels will be skipped if > 100 files changed
frontend:
  - changed-files:
    - any-glob-to-any-file: 'src/frontend/**'

backend:
  - changed-files:
    - any-glob-to-any-file: 'src/backend/**'

# Branch-based labels are NOT affected
release:
  - base-branch: 'main'

Create Workflow

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

name: "Pull Request Labeler"
on:
- pull_request_target

jobs:
  labeler:
    permissions:
      contents: read
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v6

Inputs

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

Name	Description	Default
repo-token	Token to use to authorize label changes. Typically the GITHUB_TOKEN secret	github.token
configuration-path	The path to the label configuration file. If the file doesn't exist at the specified path on the runner, action will read from the source repository via the Github API.	.github/labeler.yml
sync-labels	Whether or not to remove labels when matching files are reverted or no longer changed by the PR	false
dot	Whether or not to auto-include paths starting with dot (e.g. .github)	true
pr-number	The number(s) of pull request to update, rather than detecting from the workflow context	N/A

Using configuration-path input together with the @actions/checkout action

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:

```yml steps: - uses: actions/checkout@v5 # Uploads repository content to the runner with: r