Improve Labeler Action Documentation and Error Handling for Permissions (#897)

* Update README.md and labeler.ts to clarify permissions for GitHub Labeler Action

* Update dist/index.js with latest build changes

* Update README.md to clarify manual label creation as an alternative to granting issues write permission

* Fix labeler error handling to ensure case-insensitive check for unauthorized access

* Refactor error handling in labeler to throw an error for unauthorized access instead of logging

* Add tests for labeler error handling and improve error reporting

.github/workflows/basic-validation.yml

@@ -16,4 +16,4 @@ jobs:
     name: Basic validation
     uses: actions/reusable-workflows/.github/workflows/basic-validation.yml@main
     with:
-      node-version: '20.x'
+      node-version: '24.x'

.github/workflows/check-dist.yml

@@ -16,4 +16,4 @@ jobs:
     name: Check dist/
     uses: actions/reusable-workflows/.github/workflows/check-dist.yml@main
     with:
-      node-version: '20.x'
+      node-version: '24.x'

.github/workflows/publish-immutable-actions.yml

@@ -0,0 +1,20 @@
+name: 'Publish Immutable Action Version'
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      packages: write
+
+    steps:
+      - name: Checking out
+        uses: actions/checkout@v5
+      - name: Publish
+        id: publish
+        uses: actions/publish-immutable-action@0.0.3

.github/workflows/release-new-action-version.yml

@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Update the ${{ env.TAG_NAME }} tag
-        uses: actions/publish-action@v0.2.2
+        uses: actions/publish-action@v0.4.0
         with:
           source-tag: ${{ env.TAG_NAME }}
           slack-webhook: ${{ secrets.SLACK_WEBHOOK }}

.licenses/npm/@actions/core.dep.yml

@@ -1,6 +1,6 @@
 ---
 name: "@actions/core"
-version: 1.10.1
+version: 1.11.1
 type: npm
 summary: Actions core lib
 homepage: https://github.com/actions/toolkit/tree/main/packages/core

.licenses/npm/@actions/exec.dep.yml

@@ -0,0 +1,20 @@
+---
+name: "@actions/exec"
+version: 1.1.1
+type: npm
+summary: Actions exec lib
+homepage: https://github.com/actions/toolkit/tree/main/packages/exec
+license: mit
+licenses:
+- sources: LICENSE.md
+  text: |-
+    The MIT License (MIT)
+
+    Copyright 2019 GitHub
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+notices: []

.licenses/npm/@actions/io.dep.yml

@@ -1,20 +1,20 @@
 ---
-name: uuid
-version: 8.3.2
+name: "@actions/io"
+version: 1.1.3
 type: npm
-summary: RFC4122 (v1, v4, and v5) UUIDs
-homepage: 
+summary: Actions io lib
+homepage: https://github.com/actions/toolkit/tree/main/packages/io
 license: mit
 licenses:
 - sources: LICENSE.md
-  text: |
+  text: |-
     The MIT License (MIT)
 
-    Copyright (c) 2010-2020 Robert Kieffer and other contributors
+    Copyright 2019 GitHub
 
     Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
     The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-notices: []
+notices: []

.licenses/npm/@octokit/openapi-types-19.0.1.dep.yml

@@ -3,7 +3,7 @@ name: "@octokit/openapi-types"
 version: 19.0.1
 type: npm
 summary: Generated TypeScript definitions based on GitHub's OpenAPI spec for api.github.com
-homepage: 
+homepage:
 license: mit
 licenses:
 - sources: LICENSE

.licenses/npm/@octokit/openapi-types-23.0.1.dep.yml

@@ -0,0 +1,20 @@
+---
+name: "@octokit/openapi-types"
+version: 23.0.1
+type: npm
+summary: Generated TypeScript definitions based on GitHub's OpenAPI spec for api.github.com
+homepage:
+license: mit
+licenses:
+- sources: LICENSE
+  text: |-
+    Copyright 2020 Gregor Martynus
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+- sources: README.md
+  text: "[MIT](LICENSE)"
+notices: []

.licenses/npm/@octokit/request-error.dep.yml

@@ -1,9 +1,9 @@
 ---
 name: "@octokit/request-error"
-version: 5.0.1
+version: 5.1.1
 type: npm
 summary: Error class for Octokit request errors
-homepage: 
+homepage:
 license: mit
 licenses:
 - sources: LICENSE

.licenses/npm/@octokit/types-12.1.0.dep.yml

@@ -3,7 +3,7 @@ name: "@octokit/types"
 version: 12.1.0
 type: npm
 summary: Shared TypeScript definitions for Octokit projects
-homepage: 
+homepage:
 license: mit
 licenses:
 - sources: LICENSE

.licenses/npm/@octokit/types-13.8.0.dep.yml

@@ -0,0 +1,20 @@
+---
+name: "@octokit/types"
+version: 13.8.0
+type: npm
+summary: Shared TypeScript definitions for Octokit projects
+homepage:
+license: mit
+licenses:
+- sources: LICENSE
+  text: |
+    MIT License Copyright (c) 2019 Octokit contributors
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+- sources: README.md
+  text: "[MIT](LICENSE)"
+notices: []

.licenses/npm/brace-expansion.dep.yml

@@ -1,6 +1,6 @@
 ---
 name: brace-expansion
-version: 2.0.1
+version: 2.0.2
 type: npm
 summary: Brace expansion as known from sh/bash
 homepage: https://github.com/juliangruber/brace-expansion

.licenses/npm/minimatch.dep.yml

@@ -1,6 +1,6 @@
 ---
 name: minimatch
-version: 9.0.3
+version: 10.0.1
 type: npm
 summary: a glob matcher in javascript
 homepage: 

.licenses/npm/undici.dep.yml

@@ -1,6 +1,6 @@
 ---
 name: undici
-version: 5.26.5
+version: 5.29.0
 type: npm
 summary: An HTTP/1.1 client, written from scratch for Node.js
 homepage: https://undici.nodejs.org

README.md

@@ -4,6 +4,13 @@
 
 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](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)
+
 ## Breaking changes in V5
 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.
 
@@ -13,6 +20,9 @@ Automatically label new pull requests based on the paths of files being changed
 
 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.
 
+> [!IMPORTANT]
+> Before the update to the v5, please check out [this information](#notes-regarding-pull_request_target-event) about the `pull_request_target` event trigger.
+
 ## Usage
 
 ### Create `.github/labeler.yml`
@@ -110,6 +120,18 @@ 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:
@@ -126,14 +148,14 @@ source:
 feature:
  - head-branch: ['^feature', 'feature']
 
- # Add 'release' label to any PR that is opened against the `main` branch
+# Add 'release' label to any PR that is opened against the `main` branch
 release:
  - base-branch: 'main'
 ```
 
 ### Create Workflow
 
-Create a workflow (e.g. `.github/workflows/labeler.yml` see [Creating a Workflow file](https://help.github.com/en/articles/configuring-a-workflow#creating-a-workflow-file)) to utilize the labeler action with content:
+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:
 
 ```yml
 name: "Pull Request Labeler"
@@ -147,7 +169,7 @@ jobs:
       pull-requests: write
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/labeler@v5
+    - uses: actions/labeler@v6
 ```
 
 #### Inputs
@@ -167,10 +189,10 @@ You might want to use action called [@actions/checkout](https://github.com/actio
 
 ```yml
     steps:
-    - uses: actions/checkout@v4 # Uploads repository content to the runner
+    - uses: actions/checkout@v5 # Uploads repository content to the runner
       with:
         repository: "owner/repositoryName" # The one of the available inputs, visit https://github.com/actions/checkout#readme to find more
-    - uses: actions/labeler@v5
+    - uses: actions/labeler@v6
       with:
         configuration-path: 'path/to/the/uploaded/configuration/file'
 
@@ -193,7 +215,7 @@ jobs:
     steps:
     
     # Label PRs 1, 2, and 3
-    - uses: actions/labeler@v5
+    - uses: actions/labeler@v6
       with:        
         pr-number: |
           1
@@ -226,7 +248,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - id: label-the-PR
-      uses: actions/labeler@v5
+      uses: actions/labeler@v6
       
     - id: run-frontend-tests
       if: contains(steps.label-the-PR.outputs.all-labels, 'frontend')
@@ -241,11 +263,60 @@ jobs:
         # Put your commands for running backend tests here
 ```
 
-## Permissions
+## Recommended Permissions
 
-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`](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. 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.
+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:
+
+```yml
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+```
+
+### Manual Label Creation as an Alternative to Granting issues write Permission 
+
+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.
+
+## Notes regarding `pull_request_target` event
+
+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.
+
+```yml
+name: "Pull Request Labeler"
+on:
+- pull_request
+```
+
+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.
 
 ## Contributions
 
-Contributions are welcome! See the [Contributor's Guide](CONTRIBUTING.md).
+Contributions are welcome! See the [Contributor's Guide](CONTRIBUTING.md).

__tests__/labeler.test.ts

@@ -1,5 +1,8 @@
 import * as yaml from 'js-yaml';
 import * as core from '@actions/core';
+import * as api from '../src/api';
+import {labeler} from '../src/labeler';
+import * as github from '@actions/github';
 import * as fs from 'fs';
 import {checkMatchConfigs} from '../src/labeler';
 import {
@@ -10,6 +13,7 @@ import {
 } from '../src/api/get-label-configs';
 
 jest.mock('@actions/core');
+jest.mock('../src/api');
 
 beforeAll(() => {
   jest.spyOn(core, 'getInput').mockImplementation((name, options) => {
@@ -159,3 +163,73 @@ describe('checkMatchConfigs', () => {
     });
   });
 });
+
+describe('labeler error handling', () => {
+  const mockClient = {} as any;
+  const mockPullRequest = {
+    number: 123,
+    data: {labels: []},
+    changedFiles: []
+  };
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+
+    (github.getOctokit as jest.Mock).mockReturnValue(mockClient);
+    (api.getPullRequests as jest.Mock).mockReturnValue([
+      {
+        ...mockPullRequest,
+        data: {labels: [{name: 'old-label'}]}
+      }
+    ]);
+
+    (api.getLabelConfigs as jest.Mock).mockResolvedValue(
+      new Map([['new-label', ['dummy-config']]])
+    );
+
+    // Force match so "new-label" is always added
+    jest.spyOn({checkMatchConfigs}, 'checkMatchConfigs').mockReturnValue(true);
+  });
+
+  it('throws a custom error for HttpError 403 with "unauthorized" message', async () => {
+    (api.setLabels as jest.Mock).mockRejectedValue({
+      name: 'HttpError',
+      status: 403,
+      message: 'Request failed with status code 403: Unauthorized'
+    });
+
+    await expect(labeler()).rejects.toThrow(
+      /does not have permission to create labels/
+    );
+  });
+
+  it('rethrows unexpected HttpError', async () => {
+    const unexpectedError = {
+      name: 'HttpError',
+      status: 404,
+      message: 'Not Found'
+    };
+    (api.setLabels as jest.Mock).mockRejectedValue(unexpectedError);
+
+    // NOTE: In the current implementation, labeler rethrows the raw error object (not an Error instance).
+    // `rejects.toThrow` only works with real Error objects, so here we must use `rejects.toEqual`.
+    // If labeler is updated to always wrap errors in `Error`, this test can be changed to use `rejects.toThrow`.
+    await expect(labeler()).rejects.toEqual(unexpectedError);
+  });
+
+  it('handles "Resource not accessible by integration" gracefully', async () => {
+    const error = {
+      name: 'HttpError',
+      message: 'Resource not accessible by integration'
+    };
+    (api.setLabels as jest.Mock).mockRejectedValue(error);
+
+    await labeler();
+
+    expect(core.warning).toHaveBeenCalledWith(
+      expect.stringContaining("requires 'issues: write'"),
+      expect.any(Object)
+    );
+    expect(core.setFailed).toHaveBeenCalledWith(error.message);
+  });
+});

action.yml

@@ -28,5 +28,5 @@ outputs:
   all-labels:
     description: 'A comma-separated list of all labels that the PR contains'
 runs:
-  using: 'node20'
+  using: 'node24'
   main: 'dist/index.js'

package.json

@@ -1,8 +1,11 @@
 {
   "name": "labeler",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "Labels pull requests by files altered",
   "main": "lib/main.js",
+    "engines": {
+    "node": ">=24"
+  },
   "scripts": {
     "build": "tsc && ncc build lib/main.js",
     "format": "prettier --no-error-on-unmatched-pattern --config ./.prettierrc.js --write \"**/*.{ts,yml,yaml}\"",
@@ -24,29 +27,30 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@actions/core": "^1.10.0",
+    "@actions/core": "^1.11.1",
     "@actions/github": "^6.0.0",
     "@octokit/plugin-retry": "^6.0.0",
     "js-yaml": "^4.1.0",
     "lodash.isequal": "^4.5.0",
-    "minimatch": "^9.0.3"
+    "minimatch": "^10.0.1"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.6",
-    "@types/js-yaml": "^4.0.6",
-    "@types/lodash.isequal": "^4.5.6",
+    "@types/jest": "^29.5.14",
+    "@types/js-yaml": "^4.0.9",
+    "@types/lodash.isequal": "^4.5.8",
     "@types/minimatch": "^5.1.2",
-    "@types/node": "^20.8.8",
-    "@typescript-eslint/eslint-plugin": "^6.7.4",
-    "@typescript-eslint/parser": "^6.7.2",
-    "@vercel/ncc": "^0.38.1",
-    "eslint": "^8.51.0",
-    "eslint-config-prettier": "^9.0.0",
-    "eslint-plugin-jest": "^27.4.2",
+    "@types/node": "^24.1.0",
+    "@typescript-eslint/eslint-plugin": "^7.3.1",
+    "@typescript-eslint/parser": "^7.18.0",
+    "@vercel/ncc": "^0.38.3",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-jest": "^28.11.0",
     "eslint-plugin-node": "^11.1.0",
     "jest": "^29.7.0",
-    "prettier": "^3.0.3",
-    "ts-jest": "^29.1.1",
-    "typescript": "^5.2.2"
+    "prettier": "^3.4.2",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.3"
+
   }
 }

src/labeler.ts

@@ -22,7 +22,7 @@ export const run = () =>
     core.setFailed(error.message);
   });
 
-async function labeler() {
+export async function labeler() {
   const {token, configPath, syncLabels, dot, prNumbers} = getInputs();
 
   if (!prNumbers.length) {
@@ -65,6 +65,15 @@ async function labeler() {
       }
     } catch (error: any) {
       if (
+        error.name === 'HttpError' &&
+        error.status === 403 &&
+        error.message.toLowerCase().includes('unauthorized')
+      ) {
+        throw new Error(
+          `Failed to set labels for PR #${pullRequest.number}. The workflow does not have permission to create labels. ` +
+            `Ensure the 'issues: write' permission is granted in the workflow file or manually create the missing labels in the repository before running the action.`
+        );
+      } else if (
         error.name !== 'HttpError' ||
         error.message !== 'Resource not accessible by integration'
       ) {
@@ -72,7 +81,8 @@ async function labeler() {
       }
 
       core.warning(
-        `The action requires write permission to add labels to pull requests. For more information please refer to the action documentation: https://github.com/actions/labeler#permissions`,
+        `The action requires 'issues: write' permission to create new labels or 'pull-requests: write' permission to add existing labels to pull requests. ` +
+          `For more information, refer to the action documentation: https://github.com/actions/labeler#recommended-permissions`,
         {
           title: `${process.env['GITHUB_ACTION_REPOSITORY']} running under '${github.context.eventName}' is misconfigured`
         }