labeler

Pull Request Labeler

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

What's changed in V7

• Migrated to ESM internally to support the latest @actions/* package versions. No changes to action inputs, outputs, or behavior.

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:

…

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

…

Configuration Options

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

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

…

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:

When sync-labels is enabled, labeler synchronizes only labels whose names are present in the labeler configuration. Matching configured labels are added in one batch, and configured labels that no longer match are removed in one batch. Other labels, including labels added by users or other automation, are not rewritten or removed.

Removals and additions use separate API requests, so configured labels may be temporarily absent while a synchronization swaps stale labels for newly matching labels. Swaps can take longer than updates requiring only additions or removals because these requests run sequentially. At GitHub's 100-label limit, labels added concurrently between those requests can prevent all newly matching configured labels from being added; labeler does not remove unconfigured labels to make room.

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:

    steps:
    - uses: actions/checkout@v5 # Uploads repository content to the runner
      with:
        repository: "owner/repositoryName" # The one of the available inputs, visit https://gith