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

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

The key is the name of the label in your repository that you want to add (e.g. merge conflict, needs-updating) and the value is the path (glob) of the changed files (e.g. src/**, tests/*.spec.js) or a match object.

For more control over matching, you can provide a match object instead of a simple path glob. The match object is defined as:

- any: ['list', 'of', 'globs']
  all: ['list', 'of', 'globs']

One or both fields can be provided for fine-grained matching. Unlike the top-level list, the list of path globs provided to any and all must ALL match against a path for the label to be applied.

The fields are defined as follows:

• any: match ALL globs against ANY changed path
• all: match ALL globs against ALL changed paths

A simple path glob is the equivalent to any: ['glob']. More specifically, the following two configurations are equivalent:

label1:
- example1/*

and

label1:
- any: ['example1/*']

From a boolean logic perspective, top-level match objects are OR-ed together and individual match rules within an object are AND-ed. Combined with ! negation, you can write complex matching rules.

⚠️ This action uses minimatch to apply glob patterns. For historical reasons, paths starting with dot (e.g. .github) are not matched by default. You need to set dot: true to change this behavior. See Inputs table below for details.

# Add 'label1' to any changes within 'example' folder or any subfolders
label1:
- example/**

# Add 'label2' to any file changes within 'example2' folder
label2: example2/*

# Add label3 to any change to .txt files within the entire repository. Quotation marks are required for the leading asterisk
label3:
- '**/*.txt'

# Add 'repo' label to any root file changes
repo:
- '*'

# Add '@domain/core' label to any change within the 'core' package
'@domain/core':
- package/core/**

# Add 'test' label to any change to *.spec.js files within the source dir
test:
- src/**/*.spec.js

# Add 'source' label to any change to src files within the source dir EXCEPT for the docs sub-folder
source:
- any: ['src/**', '!src/docs/*']

# Add 'frontend` label to any change to *.js files as long as the `main.js` hasn't changed
frontend:
- any: ['src/**/*.js']
  all: ['!src/main.js']

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:
  triage:
    permissions:
      contents: read
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4

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

When dot is disabled and you want to include all files in a folder:

label1:
- path/to/folder/**/*
- path/to/folder/**/.*

If dot is enabled:

label1:
- path/to/folder/**

Labeler provides the following outputs:

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

name: "My workflow"
on:
- pull_request_target

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
    - id: label-the-PR
      uses: actions/labeler@v3
      
    - id: run-frontend-tests
      if: contains(fromJson(steps.label-the-PR.outputs.all-labels), 'frontend')
      run: |
        echo "Running frontend tests..."
        # Put your commands for running frontend tests here
  
    - id: run-backend-tests
      if: contains(fromJson(steps.label-the-PR.outputs.all-labels), 'backend')
      run: |
        echo "Running backend tests..."
        # Put your commands for running backend tests here

In order to add labels to pull requests, the GitHub labeler action requires write permissions on the pull-request. 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 instead of pull_request (see example above). This change allows the action to have write access, because pull_request_target alters the context of the action and safely grants additional permissions. Refer to the GitHub token permissions documentation for more details about access levels and event contexts.

Contributions are welcome! See the Contributor's Guide.