> Make sure your runner is on version v2.327.1 or later to ensure compatibility with this release. [Release Notes](https://github.com/actions/runner/releases/tag/v2.327.1)
For more details, see the full release notes on the [release page](https://github.com/actions/labeler/releases/tag/v6.0.0)
1) The ability to apply labels based on the names of base and/or head branches was added ([#186](https://github.com/actions/labeler/issues/186) and [#54](https://github.com/actions/labeler/issues/54)). The match object for changed files was expanded with new combinations in order to make it more intuitive and flexible ([#423](https://github.com/actions/labeler/issues/423) and [#101](https://github.com/actions/labeler/issues/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](https://github.com/actions/labeler/issues/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](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions). 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.
> Before the update to the v5, please check out [this information](#notes-regarding-pull_request_target-event) about the `pull_request_target` event trigger.
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](https://github.com/isaacs/minimatch#minimatch), and for the branches you provide a regexp to match against the branch name.
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.
-`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:
| `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
```yml
# .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
```yml
# .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
Create a workflow (e.g. `.github/workflows/labeler.yml` see [Creating a Workflow file](https://docs.github.com/en/actions/writing-workflows/quickstart#creating-your-first-workflow)) to utilize the labeler action with content:
| `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` |
| `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](https://github.com/actions/checkout) to upload label configuration file onto the runner from the current or any other repositories. See usage example below:
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 for `pull_request` events, at most. If you encounter an `Error: HttpError: Resource not accessible by integration`, it's likely due to these permission constraints. To resolve this issue, you can modify the `on:` section of your workflow to use
[`pull_request_target`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target) instead of `pull_request` (see example [above](#create-workflow)). This change allows the action to have write access, because `pull_request_target` alters the [context of the action](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target) and safely grants additional permissions.
There exists a potentially dangerous misuse of the `pull_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 that `pull_request_target` should only be used in workflows that are carefully designed to avoid executing untrusted code and to also ensure that workflows using `pull_request_target` limit access to sensitive resources. Refer to the [GitHub token permissions documentation](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) for more details about access levels and event contexts.
### Example Workflow Permissions
To ensure the action works correctly, include the following permissions in your workflow file:
If you prefer not to grant the `issues: write` permission in your workflow, you can manually create all required labels in the repository before the action runs.
Using the `pull_request_target` event trigger involves several peculiarities related to initial set up of the labeler or updating version of the labeler.
### Initial set up of the labeler action
When submitting an initial pull request to a repository using the `pull_request_target` event, the labeler workflow will not run on that pull request because the `pull_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.
### Updating major version of the labeler
When submitting a pull request that includes updates of the labeler action version and associated configuration files, using the `pull_request_target` event may result in a failed workflow. This is due to the nature of `pull_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 the `pull_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.
Once you confirm that the updated configuration files function as intended, you can then revert to using the `pull_request_target` event before merging the pull request. Following this step ensures that your workflow is robust and free from disruptions.
