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
Bump brace-expansion from 1.1.11 to 1.1.12 and document breaking changes in v6 (#877 )
2025-12-10 11:41:56 +00:00 · 2025-09-19 14:46:04 -05:00 · 2025-09-16 13:25:22 -05:00
6 changed files with 161 additions and 33 deletions
--- a/.licenses/npm/brace-expansion.dep.yml
+++ b/.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
--- a/README.md
+++ b/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.

@@ -258,15 +265,36 @@ jobs:

 ## 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. 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 advisible 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.
+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.
@@ -291,4 +319,4 @@ Once you confirm that the updated configuration files function as intended, you

 ## Contributions

-Contributions are welcome! See the [Contributor's Guide](CONTRIBUTING.md).
+Contributions are welcome! See the [Contributor's Guide](CONTRIBUTING.md).
--- a/tests/labeler.test.ts
+++ b/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);
+  });
+});
--- a/dist/index.js
+++ b/dist/index.js
@@ -1028,6 +1028,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.run = void 0;
+exports.labeler = labeler;
 exports.checkMatchConfigs = checkMatchConfigs;
 exports.checkAny = checkAny;
 exports.checkAll = checkAll;
@@ -1083,11 +1084,18 @@ function labeler() {
                    }
                }
                catch (error) {
-                    if (error.name !== 'HttpError' ||
+                    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') {
                        throw error;
                    }
-                    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#recommended-permissions`, {
+                    core.warning(`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`
                    });
                    core.setFailed(error.message);
@@ -11707,7 +11715,7 @@ function expand(str, isTop) {
    var isOptions = m.body.indexOf(',') >= 0;
    if (!isSequence && !isOptions) {
      // {a},b}
-      if (m.post.match(/,.*\}/)) {
+      if (m.post.match(/,(?!,).*\}/)) {
        str = m.pre + '{' + m.body + escClose + m.post;
        return expand(str);
      }
--- a/package-lock.json
+++ b/package-lock.json
@@ -799,10 +799,11 @@
      }
    },
    "node_modules/@eslint/eslintrc/node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
+      "license": "MIT",
      "dependencies": {
        "balanced-match": "^1.0.0",
        "concat-map": "0.0.1"
@@ -852,10 +853,11 @@
      }
    },
    "node_modules/@humanwhocodes/config-array/node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
+      "license": "MIT",
      "dependencies": {
        "balanced-match": "^1.0.0",
        "concat-map": "0.0.1"
@@ -2254,9 +2256,10 @@
      "integrity": "sha512-VHiNCbI1lKdl44tGrhNfU3lup0Tj/ZBMJB5/2ZbNXRCPuRCO7ed2mgcK4r17y+KB2EfuYuRaVlwNbAeaWGSpbw=="
    },
    "node_modules/brace-expansion": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz",
-      "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==",
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
+      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
+      "license": "MIT",
      "dependencies": {
        "balanced-match": "^1.0.0"
      }
@@ -2806,10 +2809,11 @@
      }
    },
    "node_modules/eslint-plugin-node/node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
+      "license": "MIT",
      "dependencies": {
        "balanced-match": "^1.0.0",
        "concat-map": "0.0.1"
@@ -2889,10 +2893,11 @@
      }
    },
    "node_modules/eslint/node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
+      "license": "MIT",
      "dependencies": {
        "balanced-match": "^1.0.0",
        "concat-map": "0.0.1"
@@ -3276,10 +3281,11 @@
      }
    },
    "node_modules/glob/node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
+      "license": "MIT",
      "dependencies": {
        "balanced-match": "^1.0.0",
        "concat-map": "0.0.1"
@@ -3635,10 +3641,11 @@
      }
    },
    "node_modules/jake/node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
+      "license": "MIT",
      "dependencies": {
        "balanced-match": "^1.0.0",
        "concat-map": "0.0.1"
@@ -5179,10 +5186,11 @@
      }
    },
    "node_modules/test-exclude/node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
      "dev": true,
+      "license": "MIT",
      "dependencies": {
        "balanced-match": "^1.0.0",
        "concat-map": "0.0.1"
--- a/src/labeler.ts
+++ b/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#recommended-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`
        }