actions/labeler v7: Path and Branch Based PR Labeling, Now on ESM

What Problem Does It Solve

Manually triaging pull requests by adding labels is repetitive and error prone. actions/labeler automates that by applying labels based on two signals: which files changed and what the base or head branch is named. It is aimed at maintainers who want consistent labeling for documentation changes, frontend versus backend work, or release branches. The action runs as a GitHub Actions step and reads a YAML config file from the repository. It does not inspect code, commits, or PR descriptions. That narrow scope is both its strength and its limit.

How the Matching Logic Works

The configuration file .github/labeler.yml maps label names to match objects. Each match object can contain changed-files, base-branch, or head-branch keys. For changed files, you provide minimatch glob patterns. For branches, you provide regexps. The logic combines these with boolean semantics. Top-level keys and options inside an all block are AND-ed, while individual rules inside an any block are OR-ed. If you omit the top-level any or all key, the default is any. The README gives an example where a Documentation label with any-glob-to-any-file: 'docs/*' is equivalent to an explicit any wrapper. This structure lets you express rules like 'label if any file in src changed and the head branch is a feature branch'.

Configuration Options and Limits

Two top-level options control how many labels the action can apply. changed-files-labels-limit caps the number of new labels applied from changed files. max-files-changed sets a maximum total changed file count; if exceeded, all file-based labeling is skipped. These exist to handle large pull requests like tree-wide refactors that would otherwise trigger dozens of labels. The README notes that if the limit is exceeded, no changed-files labels are applied for that run. This is a blunt instrument. You cannot say 'apply only the first three matching labels'. The action simply aborts file-based labeling. Branch-based labeling is not affected by these limits, since it does not depend on file counts.

Getting It Running

To use the action, create .github/labeler.yml with your rules. Then add a workflow step. The README does not include a full workflow YAML, but the standard usage is to reference actions/labeler@v7 with a pull_request or pull_request_target trigger. The labels you reference in the config must already exist in the repository. The action does not create them. A basic config looks like this: Documentation: - changed-files: - any-glob-to-any-file: 'docs/**'. For branch matching, you use base-branch or head-branch with regexps, for example release-.*. The v7 release notes state there are no changes to inputs, outputs, or behavior compared to v6. The only internal change is the migration to ESM to support newer @actions/* packages.

Breaking Changes and Runner Requirements

Version 6 upgraded the runtime from Node 20 to Node 24. That requires your GitHub Actions runner to be at least version 2.327.1. If you use older self-hosted runners, the action may fail. Version 5 redesigned the configuration file structure. The match object syntax changed significantly, and old v4 configs are not compatible. The README warns to read the documentation before upgrading. Also, v5 changed the default for the dot input to true, so paths starting with a dot like .github are now matched by default. That can surprise you if you previously relied on dot files being ignored. The v5 notes also flag the pull_request_target event and advise checking the relevant security information before using that trigger.

A Real Alternative: Dependabot or Custom Scripts

The main alternative is not another action but writing your own labeling logic in a workflow step using a shell script or a language like Python. That gives you full control over matching rules, such as reading PR titles or commit messages. However, it requires maintaining code and handling edge cases like glob expansion and regex escaping. Another alternative is to use GitHub's built-in branch protection rules with required labels, but that only enforces a single label, not dynamic assignment. If you need labels based on PR content, actions/labeler is the wrong tool. Its matching is purely path and branch based. A custom script could parse the PR body for keywords, but you would lose the simplicity of a declarative YAML config.

Maintenance and Upgrade Cost

The action is maintained by GitHub, which reduces the burden of keeping it current. The v7 release is a minor internal change with no user-facing impact. The bigger cost is config migration when major versions change. The v5 rewrite broke existing configs, and v6 required runner updates. You should pin to a specific major version, like @v7, to avoid unexpected breaking changes. The license is MIT, so you can fork and modify it if needed. The codebase is TypeScript, which makes contributions approachable. However, the action depends on the @actions/* packages, and the ESM migration in v7 suggests those dependencies are evolving. If you fork, you inherit that maintenance burden. The README does not document a deprecation policy, so you should watch release notes before upgrading major versions.

Editorial conclusion

Adopt actions/labeler if you want deterministic, path-based PR labeling without maintaining custom scripts. It fits repositories with clear directory structures and branch naming conventions. Avoid it if your labeling rules depend on PR content, author, or external context, since the action only sees files and branch names. Before adopting, verify your runner is at least v2.327.1 for Node 24 support, and test your labeler.yml against the v5 config schema, as old v4 configs will break. Also check the pull_request_target notes if you use that event, since the action's behavior and security implications differ.

Official sources

1. Official README
2. Project repository
3. Release notes