Merge pull request #4217 from github/mario-campos/warn-on-changelog-write

Add `post-comment` Action

.github/actions/post-comment/action.yml

@@ -0,0 +1,41 @@
+name: "Post comment"
+description: "Create or update a sticky PR comment identified by a caller-provided marker."
+inputs:
+  marker:
+    description: >
+      Non-empty plain-text identifier for the comment. Use a unique, stable value
+      for each distinct comment; it is automatically wrapped in a hidden HTML comment.
+    required: true
+  body:
+    description: "Full comment markdown."
+    required: true
+  update-only:
+    description: Do nothing if no comment with the specified marker exists.
+    required: false
+    default: "false"
+  issue-id:
+    description: >
+      The issue or pull request number to post/update the comment on.
+      Defaults to the current pull request if not provided.
+    required: false
+  token:
+    description: "The GitHub token to authenticate with."
+    required: true
+runs:
+  using: composite
+  steps:
+    - name: Post comment
+      shell: bash
+      env:
+        BODY: ${{ inputs.body }}
+        MARKER: ${{ inputs.marker }}
+        UPDATE_ONLY: ${{ case(inputs.update-only == 'true', '--update-only', '') }}
+        GH_TOKEN: ${{ inputs.token }}
+        ISSUE_ID: ${{ inputs.issue-id || github.event.pull_request.number }}
+      run: |
+        npx tsx ./pr-checks/post-comment.ts \
+          --body "$BODY" \
+          --marker "$MARKER" \
+          $UPDATE_ONLY \
+          --issue-id "$ISSUE_ID" \
+          --repository "$GITHUB_REPOSITORY"

.github/actions/prepare-test/action.yml

@@ -36,7 +36,14 @@ runs:
         set -e # Fail this Action if `gh release list` fails.
 
         if [[ "$VERSION" == "nightly" || "$VERSION" == "nightly-latest" ]]; then
-          echo "tools-url=nightly" >> "$GITHUB_OUTPUT"
+          if [[ "$USE_ALL_PLATFORM_BUNDLE" == "true" ]]; then
+            # With `tools: nightly`, the Action downloads the bundle for the runner's platform, so look
+            # up the latest nightly release here to get its all-platform bundle instead.
+            tag=$(gh release list --repo dsp-testing/codeql-cli-nightlies --limit 1 --json tagName --jq '.[0].tagName')
+            echo "tools-url=https://github.com/dsp-testing/codeql-cli-nightlies/releases/download/$tag/codeql-bundle.tar.gz" >> "$GITHUB_OUTPUT"
+          else
+            echo "tools-url=nightly" >> "$GITHUB_OUTPUT"
+          fi
           exit 0
         elif [[ "$VERSION" == "linked" ]]; then
           echo "tools-url=linked" >> "$GITHUB_OUTPUT"

.github/workflows/__all-platform-bundle.yml

@@ -92,6 +92,18 @@ jobs:
           # Swift is not supported on Ubuntu so we manually exclude it from the list here
           languages: cpp,csharp,go,java,javascript,python,ruby
           tools: ${{ steps.prepare-test.outputs.tools-url }}
+      - name: Check that the bundle contains tools for all platforms
+        env:
+          CODEQL_PATH: ${{ steps.init.outputs.codeql-path }}
+        run: |
+          # Platform-specific bundles only contain the tools for their own platform.
+          tools_dir="$(dirname "$CODEQL_PATH")/tools"
+          for platform in linux64 osx64 win64; do
+            if [[ ! -d "$tools_dir/$platform" ]]; then
+              echo "::error::Expected an all-platform CodeQL bundle, but '$tools_dir' does not contain a '$platform' directory."
+              exit 1
+            fi
+          done
       - name: Build code
         run: ./build.sh
       - uses: ./../action/analyze

.github/workflows/codeql.yml

@@ -79,7 +79,6 @@ jobs:
           - ubuntu-24.04
           - windows-2022
           - windows-2025
-          - macos-14-xlarge
           - macos-15-xlarge
         tools: ${{ fromJson(needs.check-codeql-versions.outputs.versions) }}
     runs-on: ${{ matrix.os }}

.github/workflows/deflake.yml

@@ -31,7 +31,6 @@ on:
       - "PR Check - C/C\\+\\+: autoinstalling dependencies is skipped (macOS)"
       - "PR Check - C/C\\+\\+: disabling autoinstalling dependencies (Linux)"
       - "PR Check - Clean up database cluster directory"
-      - "PR Check - CodeQL Bundle All"
       - "PR Check - Config export"
       - "PR Check - Config input"
       - "PR Check - Custom source root"

.github/workflows/test-codeql-bundle-all.yml

@@ -1,62 +0,0 @@
-name: "PR Check - CodeQL Bundle All"
-env:
-  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  GO111MODULE: auto
-on:
-  push:
-    branches:
-      - main
-      - releases/v*
-  pull_request:
-  merge_group:
-    types: [checks_requested]
-  schedule:
-    - cron: "0 5 * * *"
-  workflow_dispatch:
-
-concurrency:
-  cancel-in-progress: ${{ github.event_name == 'pull_request' || false }}
-  group: ${{ github.workflow }}-${{ github.ref }}
-
-defaults:
-  run:
-    shell: bash
-jobs:
-  test-codeql-bundle-all:
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-26.04
-            version: nightly-latest
-    name: "CodeQL Bundle All"
-    if: github.triggering_actor != 'dependabot[bot]'
-    permissions:
-      contents: read
-      security-events: read
-    timeout-minutes: 45
-    runs-on: ${{ matrix.os }}
-    steps:
-      - name: Check out repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - name: Prepare test
-        id: prepare-test
-        uses: ./.github/actions/prepare-test
-        with:
-          version: ${{ matrix.version }}
-          use-all-platform-bundle: true
-      - name: Install .NET
-        uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
-        with:
-          dotnet-version: "9.x"
-      - id: init
-        uses: ./../action/init
-        with:
-          # We manually exclude Swift from the languages list here, as it is not supported on Ubuntu
-          languages: cpp,csharp,go,java,javascript,python,ruby
-          tools: ${{ steps.prepare-test.outputs.tools-url }}
-      - name: Build code
-        run: ./build.sh
-      - uses: ./../action/analyze
-    env:
-      CODEQL_ACTION_TEST_MODE: true

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 See the [releases page](https://github.com/github/codeql-action/releases) for the relevant changes to the CodeQL CLI and language packs.
 
+## [UNRELEASED]
+
+No user facing changes.
+
 ## 4.39.3 - 04 Nov 2026
 
 - Fixed diff-informed alert filtering incorrectly removing alerts in changed files whose paths contain spaces, special characters, or non-ASCII characters. [#4283](https://github.com/github/codeql-action/pull/4283)

lib/entry-points.js

@@ -178724,7 +178724,7 @@ function getDiffRangesJsonFilePath(env = getEnv()) {
   return path2.join(getTemporaryDirectory(env), PR_DIFF_RANGE_JSON_FILENAME);
 }
 function getActionVersion() {
-  return "4.39.3";
+  return "4.39.4";
 }
 function getWorkflowEventName(env = getEnv()) {
   return env.getRequired("GITHUB_EVENT_NAME" /* GITHUB_EVENT_NAME */);
@@ -184864,13 +184864,16 @@ async function deleteToolcacheBundles({
       }
       const versionDirectory = path12.join(toolDirectory, entry.name);
       try {
+        const deletionStart = import_perf_hooks3.performance.now();
         await fs15.promises.rm(versionDirectory, {
           force: true,
           recursive: true
         });
         deletedVersions.push(entry.name);
         logger2.info(
-          `Deleted the CodeQL tools at '${versionDirectory}' from the toolcache to free up disk space.`
+          `Deleted the CodeQL tools at '${versionDirectory}' from the toolcache to free up disk space (${formatDuration(
+            durationMsSince(deletionStart)
+          )}).`
         );
       } catch (e) {
         failed = true;
@@ -185369,13 +185372,14 @@ async function tryDeleteToolcacheBundles({
   if (!isGitHubHostedRunner(env) || !isToolcacheOnWorkspaceFilesystem(logger2)) {
     return;
   }
+  const startTime = import_perf_hooks4.performance.now();
   const result = await deleteToolcacheBundles({ env, logger: logger2 });
   addNoLanguageDiagnostic(
     void 0,
     makeTelemetryDiagnostic(
       "codeql-action/toolcache-bundle-cleanup",
       "Toolcache CodeQL bundle cleanup",
-      { ...result }
+      { ...result, durationMs: durationMsSince(startTime) }
     )
   );
 }

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "codeql",
-  "version": "4.39.3",
+  "version": "4.39.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "codeql",
-      "version": "4.39.3",
+      "version": "4.39.4",
       "license": "MIT",
       "workspaces": [
         "pr-checks"

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeql",
-  "version": "4.39.3",
+  "version": "4.39.4",
   "private": true,
   "description": "CodeQL action",
   "scripts": {

pr-checks/api-client.ts

@@ -8,3 +8,14 @@ export function getApiClient(token: string): ApiClient {
   const opts = githubUtils.getOctokitOptions(token);
   return new githubUtils.GitHub(opts);
 }
+
+/** Resolves the GitHub API token to use, from `GH_TOKEN` or `GITHUB_TOKEN`. */
+export function resolveToken(env: NodeJS.ProcessEnv): string {
+  const token = env.GH_TOKEN?.trim() || env.GITHUB_TOKEN?.trim();
+  if (!token) {
+    throw new Error(
+      "Missing authentication token. Set GH_TOKEN or GITHUB_TOKEN.",
+    );
+  }
+  return token;
+}

pr-checks/checks/all-platform-bundle.yml

@@ -17,6 +17,18 @@ steps:
       # Swift is not supported on Ubuntu so we manually exclude it from the list here
       languages: cpp,csharp,go,java,javascript,python,ruby
       tools: ${{ steps.prepare-test.outputs.tools-url }}
+  - name: Check that the bundle contains tools for all platforms
+    env:
+      CODEQL_PATH: ${{ steps.init.outputs.codeql-path }}
+    run: |
+      # Platform-specific bundles only contain the tools for their own platform.
+      tools_dir="$(dirname "$CODEQL_PATH")/tools"
+      for platform in linux64 osx64 win64; do
+        if [[ ! -d "$tools_dir/$platform" ]]; then
+          echo "::error::Expected an all-platform CodeQL bundle, but '$tools_dir' does not contain a '$platform' directory."
+          exit 1
+        fi
+      done
   - name: Build code
     run: ./build.sh
   - uses: ./../action/analyze

pr-checks/excluded.yml

@@ -24,3 +24,5 @@ is:
   # PRs), so requiring them would block the PRs they don't run on.
   - "github-advanced-security"
   - "License compliance check"
+  # Only runs when a PR is removed from the merge queue.
+  - "Notify"

pr-checks/post-comment.test.ts

@@ -0,0 +1,344 @@
+#!/usr/bin/env npx tsx
+
+/*
+Tests for post-comment.ts.
+*/
+
+import * as assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { type ApiClient, resolveToken } from "./api-client";
+import {
+  findExistingComment,
+  type Options,
+  parseOptions,
+  setComment,
+} from "./post-comment";
+
+/** A baseline set of valid CLI flags, as an array, for use in parseOptions tests. */
+const validFlags = [
+  "--body",
+  "hello",
+  "--marker",
+  "marker",
+  "--issue-id",
+  "42",
+  "--repository",
+  "github/codeql-action",
+];
+
+/** Returns a copy of `validFlags` with the value following `flag` replaced by `value`. */
+function withFlag(flag: string, value: string): string[] {
+  const flags = [...validFlags];
+  const index = flags.indexOf(flag);
+  flags[index + 1] = value;
+  return flags;
+}
+
+/** Returns a copy of `validFlags` with `flag` (and its value) removed entirely. */
+function withoutFlag(flag: string): string[] {
+  const flags = [...validFlags];
+  const index = flags.indexOf(flag);
+  flags.splice(index, 2);
+  return flags;
+}
+
+describe("parseOptions", async () => {
+  await it("parses valid flags", () => {
+    const options = parseOptions(validFlags);
+    assert.deepEqual(options, {
+      body: "hello",
+      marker: "marker",
+      updateOnly: false,
+      issueId: 42,
+      repository: { owner: "github", repo: "codeql-action" },
+    });
+  });
+
+  await it("enables update-only mode when --update-only is supplied", () => {
+    const options = parseOptions([...validFlags, "--update-only"]);
+    assert.equal(options.updateOnly, true);
+  });
+
+  await it("rejects a missing --body", () => {
+    assert.throws(
+      () => parseOptions(withoutFlag("--body")),
+      /Missing required flag --body/,
+    );
+  });
+
+  await it("rejects an empty --body", () => {
+    assert.throws(
+      () => parseOptions(withFlag("--body", "")),
+      /The value for --body cannot be empty/,
+    );
+  });
+
+  await it("rejects a whitespace-only --body", () => {
+    assert.throws(
+      () => parseOptions(withFlag("--body", " \t\n")),
+      /The value for --body cannot be empty/,
+    );
+  });
+
+  await it("rejects a missing --marker", () => {
+    assert.throws(
+      () => parseOptions(withoutFlag("--marker")),
+      /Missing required flag --marker/,
+    );
+  });
+
+  await it("rejects an empty --marker", () => {
+    assert.throws(
+      () => parseOptions(withFlag("--marker", "")),
+      /The value for --marker cannot be empty/,
+    );
+  });
+
+  await it("rejects a whitespace-only --marker", () => {
+    assert.throws(
+      () => parseOptions(withFlag("--marker", " \t\n")),
+      /The value for --marker cannot be empty/,
+    );
+  });
+
+  await it("rejects a missing --repository", () => {
+    assert.throws(
+      () => parseOptions(withoutFlag("--repository")),
+      /Missing required flag --repository/,
+    );
+  });
+
+  await it("rejects an empty --repository", () => {
+    assert.throws(
+      () => parseOptions(withFlag("--repository", "")),
+      /The value for --repository cannot be empty/,
+    );
+  });
+
+  await it("rejects a whitespace-only --repository", () => {
+    assert.throws(
+      () => parseOptions(withFlag("--repository", " \t\n")),
+      /The value for --repository cannot be empty/,
+    );
+  });
+
+  await it("rejects an invalid --repository value", () => {
+    assert.throws(
+      () => parseOptions(withFlag("--repository", "github/codeql/action")),
+      /Invalid --repository value/,
+    );
+  });
+});
+
+describe("resolveToken", async () => {
+  await it("reads the token from GH_TOKEN", () => {
+    assert.equal(
+      resolveToken({ GH_TOKEN: "gh-token", GITHUB_TOKEN: "gha-token" }),
+      "gh-token",
+    );
+  });
+
+  await it("falls back to GITHUB_TOKEN", () => {
+    assert.equal(resolveToken({ GITHUB_TOKEN: "gha-token" }), "gha-token");
+  });
+
+  await it("throws when no token is set", () => {
+    assert.throws(() => resolveToken({}), /Missing authentication token/);
+  });
+});
+
+/** A minimal fake of the subset of `ApiClient` used by post-comment.ts. */
+function fakeClient(existingComments: Array<{ id: number; body?: string }>) {
+  const comments = existingComments.map((comment) => ({ ...comment }));
+  let nextId =
+    comments.reduce((maxId, comment) => Math.max(maxId, comment.id), 0) + 1;
+
+  const client = {
+    paginate: async () => comments,
+    rest: {
+      issues: {
+        listComments: () => {},
+        createComment: async ({ body }: { body: string }) => {
+          comments.push({ id: nextId++, body });
+        },
+        updateComment: async ({
+          comment_id,
+          body,
+        }: {
+          comment_id: number;
+          body: string;
+        }) => {
+          const comment = comments.find(({ id }) => id === comment_id);
+          assert.ok(comment, `Comment ${comment_id} does not exist.`);
+          comment.body = body;
+        },
+      },
+    },
+  };
+
+  return { client: client as unknown as ApiClient, comments };
+}
+
+describe("findExistingComment", async () => {
+  await it("finds the id of the first comment containing the marker", async () => {
+    const { client } = fakeClient([
+      { id: 1, body: "unrelated" },
+      { id: 2, body: "<!-- marker -->\nhello" },
+      { id: 3, body: "<!-- marker -->\nanother" },
+    ]);
+    const id = await findExistingComment(
+      client,
+      { owner: "owner", repo: "repo" },
+      1,
+      "marker",
+    );
+    assert.equal(id, 3);
+  });
+
+  await it("returns undefined when no comment matches", async () => {
+    const { client } = fakeClient([{ id: 1, body: "unrelated" }]);
+    const id = await findExistingComment(
+      client,
+      { owner: "owner", repo: "repo" },
+      1,
+      "marker",
+    );
+    assert.equal(id, undefined);
+  });
+});
+
+/** A baseline set of `Options`, for use in `setComment` tests. */
+const baseOptions: Options = {
+  body: "hello",
+  marker: "marker",
+  updateOnly: false,
+  issueId: 42,
+  repository: { owner: "owner", repo: "repo" },
+};
+
+function assertCommentContent(
+  comment: { body?: string },
+  marker: string,
+  body: string,
+): void {
+  assert.ok(comment.body?.startsWith(`<!-- ${marker} -->`));
+  assert.ok(comment.body?.endsWith(body));
+}
+
+describe("setComment", async () => {
+  await it("does not create a comment in update-only mode when none exists", async () => {
+    const { client, comments } = fakeClient([]);
+
+    await setComment(client, { ...baseOptions, updateOnly: true });
+
+    // Resolution does not introduce a warning that was never posted.
+    assert.deepEqual(comments, []);
+  });
+
+  await it("leaves unrelated comments unchanged in update-only mode", async () => {
+    const originalComments = [{ id: 7, body: "unrelated" }];
+    const { client, comments } = fakeClient(originalComments);
+
+    await setComment(client, { ...baseOptions, updateOnly: true });
+
+    // Unrelated comments neither trigger resolution nor get overwritten.
+    assert.deepEqual(comments, originalComments);
+  });
+
+  await it("uses the supplied marker without affecting other comments", async () => {
+    const marker = "custom-warning";
+    const { client, comments } = fakeClient([
+      { id: 1, body: "<!-- marker -->\nunrelated warning" },
+      { id: 2, body: "<!-- custom-warning -->\nold warning" },
+    ]);
+    const options = parseOptions(withFlag("--marker", marker));
+
+    await setComment(client, options);
+
+    // Only the comment with the supplied marker changes.
+    assert.equal(comments.length, 2);
+    assert.deepEqual(comments[0], {
+      id: 1,
+      body: "<!-- marker -->\nunrelated warning",
+    });
+    assert.equal(comments[1].id, 2);
+    assertCommentContent(comments[1], marker, options.body);
+  });
+
+  await it("creates a new comment with the marker prepended", async () => {
+    const { client, comments } = fakeClient([]);
+    // No comment has the marker before posting.
+    assert.equal(comments.length, 0);
+    assert.ok(
+      !comments.some(({ body }) => body?.startsWith("<!-- marker -->")),
+    );
+
+    await setComment(client, baseOptions);
+
+    // Posting adds exactly one comment with the marker before the body.
+    assert.equal(comments.length, 1);
+    assertCommentContent(comments[0], baseOptions.marker, baseOptions.body);
+  });
+
+  await it("creates a new comment when no existing comment matches", async () => {
+    const originalComments = [
+      { id: 7, body: "unrelated" },
+      { id: 2, body: "another unrelated comment" },
+    ];
+    const { client, comments } = fakeClient(originalComments);
+    // Existing comments do not match the marker.
+    assert.ok(
+      !comments.some(({ body }) => body?.startsWith("<!-- marker -->")),
+    );
+
+    await setComment(client, baseOptions);
+
+    // A new comment is added without changing unrelated comments.
+    assert.equal(comments.length, originalComments.length + 1);
+    assert.deepEqual(
+      comments.slice(0, originalComments.length),
+      originalComments,
+    );
+    const markedComments = comments.filter(({ body }) =>
+      body?.startsWith("<!-- marker -->"),
+    );
+    // Exactly one comment contains the expected marker and body.
+    assert.equal(markedComments.length, 1);
+    assertCommentContent(
+      markedComments[0],
+      baseOptions.marker,
+      baseOptions.body,
+    );
+    // The new comment's ID does not collide with existing IDs.
+    assert.equal(new Set(comments.map(({ id }) => id)).size, comments.length);
+  });
+
+  await it("updates the existing comment when one is found", async () => {
+    const { client, comments } = fakeClient([
+      { id: 7, body: "<!-- marker -->\nold" },
+    ]);
+
+    await setComment(client, baseOptions);
+
+    // Updating preserves the comment's ID without creating a duplicate.
+    assert.equal(comments.length, 1);
+    assert.equal(comments[0].id, 7);
+    assertCommentContent(comments[0], baseOptions.marker, baseOptions.body);
+  });
+
+  await it("replaces a warning with the resolved state using the same marker", async () => {
+    const { client, comments } = fakeClient([
+      { id: 9, body: "<!-- marker -->\nold" },
+    ]);
+    const body =
+      "`CHANGELOG.md` is not modified in this PR. No changelog action is needed.";
+
+    await setComment(client, { ...baseOptions, body, updateOnly: true });
+
+    // The resolved state replaces the warning on the same marked comment.
+    assert.equal(comments.length, 1);
+    assert.equal(comments[0].id, 9);
+    assertCommentContent(comments[0], baseOptions.marker, body);
+  });
+});

pr-checks/post-comment.ts

@@ -0,0 +1,180 @@
+#!/usr/bin/env npx tsx
+
+/*
+Creates or updates a pull-request comment identified by a marker.
+
+The marker is supplied via `--marker` and must be a non-empty plain-text identifier.
+The CLI wraps the marker in a hidden HTML comment, prepends it to `--body`,
+and uses it to find the comment on later runs.
+
+Supply `--update-only` to suppress creation of comment; omit it
+to update or create comments.
+
+Example:
+```sh
+GH_TOKEN=<token> npx tsx ./pr-checks/post-comment.ts \
+  --body "The changelog needs updating." \
+  --marker "my-bot" \
+  --issue-id 123 \
+  --repository github/codeql-action
+```
+*/
+
+import assert from "node:assert/strict";
+import { parseArgs } from "node:util";
+
+import { parseRepositoryNwo, type RepositoryNwo } from "../src/repository";
+
+import { type ApiClient, getApiClient, resolveToken } from "./api-client";
+
+/** Represents the command-line options. */
+export interface Options {
+  /** The full comment body. */
+  body: string;
+  /** Plain-text identifier wrapped in a hidden HTML comment. */
+  marker: string;
+  /** Whether to only update a comment if a matching marker exists. */
+  updateOnly: boolean;
+  /** The issue/pull request number to post/update the comment on. */
+  issueId: number;
+  /** The repository to operate on. */
+  repository: RepositoryNwo;
+}
+
+function hiddenMarker(marker: string): string {
+  return `<!-- ${marker} -->`;
+}
+
+/** Parses CLI arguments supplied by the composite action into `Options`. */
+export function parseOptions(argv?: string[]): Options {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      body: { type: "string" },
+      marker: { type: "string" },
+      "update-only": { type: "boolean", default: false },
+      "issue-id": { type: "string" },
+      repository: { type: "string" },
+    },
+    strict: true,
+  });
+
+  assert(values.body !== undefined, "Missing required flag --body.");
+  assert(values.body.trim() !== "", "The value for --body cannot be empty.");
+  assert(values.marker !== undefined, "Missing required flag --marker.");
+  assert(
+    values.marker.trim() !== "",
+    "The value for --marker cannot be empty.",
+  );
+  assert(
+    values.repository !== undefined,
+    "Missing required flag --repository.",
+  );
+  assert(
+    values.repository.trim() !== "",
+    "The value for --repository cannot be empty.",
+  );
+  assert(
+    /^[\w.-]+\/[\w.-]+$/.test(values.repository),
+    "Invalid --repository value.",
+  );
+
+  return {
+    body: values.body,
+    marker: values.marker,
+    updateOnly: values["update-only"],
+    issueId: Number(values["issue-id"]),
+    repository: parseRepositoryNwo(values.repository),
+  };
+}
+
+/**
+ * Finds the first comment on the given issue/pull request whose body starts with `marker`, if any.
+ */
+export async function findExistingComment(
+  client: ApiClient,
+  repository: RepositoryNwo,
+  issueNumber: number,
+  marker: string,
+): Promise<number | undefined> {
+  const formattedMarker = hiddenMarker(marker);
+  const comments = await client.paginate(client.rest.issues.listComments, {
+    ...repository,
+    issue_number: issueNumber,
+    per_page: 100,
+  });
+  const markedComments = comments.filter((comment) =>
+    comment.body?.startsWith(formattedMarker),
+  );
+  if (markedComments.length > 1) {
+    console.warn(
+      `Found ${markedComments.length} comments with marker "${formattedMarker}". ` +
+        "Updating the first one and leaving the others unchanged. " +
+        "Use a unique marker for each distinct managed comment to avoid this situation.",
+    );
+  }
+  return markedComments.at(-1)?.id;
+}
+
+/**
+ * Creates or updates a marked comment using `client` to talk to the GitHub API.
+ */
+export async function setComment(
+  client: ApiClient,
+  options: Options,
+): Promise<void> {
+  const { issueId, marker, repository } = options;
+  const body = `${hiddenMarker(marker)}\n${options.body}`;
+
+  const existingCommentId = await findExistingComment(
+    client,
+    repository,
+    issueId,
+    marker,
+  );
+  if (existingCommentId === undefined) {
+    if (options.updateOnly) {
+      console.info(
+        "No existing comment found; skipping creation because --update-only was specified.",
+      );
+      return;
+    }
+    console.info("No existing comment found; creating a new comment.");
+    await client.rest.issues.createComment({
+      ...repository,
+      issue_number: issueId,
+      body,
+    });
+  } else {
+    console.info(`Updating existing comment ${existingCommentId}.`);
+    await client.rest.issues.updateComment({
+      ...repository,
+      comment_id: existingCommentId,
+      body,
+    });
+  }
+}
+
+async function main(): Promise<number> {
+  const options = parseOptions();
+
+  const token = resolveToken(process.env);
+  const client = getApiClient(token);
+
+  await setComment(client, options);
+
+  return 0;
+}
+
+async function run(): Promise<void> {
+  try {
+    process.exit(await main());
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+if (import.meta.main) {
+  void run();
+}

src/feature-flags.ts

@@ -6,6 +6,7 @@ import * as semver from "semver";
 import { getApiClient } from "./api-client";
 import type { CodeQL } from "./codeql";
 import * as defaults from "./defaults.json";
+import { Feature } from "./feature-flags/features";
 import { Logger } from "./logging";
 import {
   CODEQL_OVERLAY_MINIMUM_VERSION,
@@ -21,6 +22,8 @@ import { RepositoryNwo } from "./repository";
 import { ToolsFeature } from "./tools-features";
 import * as util from "./util";
 
+export { Feature } from "./feature-flags/features";
+
 const DEFAULT_VERSION_FEATURE_FLAG_PREFIX = "default_codeql_version_";
 const DEFAULT_VERSION_FEATURE_FLAG_SUFFIX = "_enabled";
 
@@ -61,107 +64,6 @@ export interface CodeQLDefaultVersionInfo {
   toolsFeatureFlagsValid?: boolean;
 }
 
-/**
- * Features as named by the GitHub API endpoint.
- *
- * Do not include the `codeql_action_` prefix as this is stripped by the API
- * endpoint.
- *
- * Legacy features should end with `_enabled`.
- */
-export enum Feature {
-  /** Allows supported properties of configuration files to be merged. */
-  AllowMergeConfigFiles = "allow_merge_config_files",
-  /** Controls whether we allow multiple values for the `analysis-kinds` input. */
-  AllowMultipleAnalysisKinds = "allow_multiple_analysis_kinds",
-  /**
-   * Whether to check for unsupported traced analysis. Primarily intended as an override to disable
-   * the check if it causes problems somehow.
-   */
-  CheckUnsupportedTracedAnalysis = "check_unsupported_traced_analysis",
-  /** Whether to allow the `config-file` input to be specified via a repository property. */
-  ConfigFileRepositoryProperty = "config_file_repository_property",
-  CppDependencyInstallation = "cpp_dependency_installation_enabled",
-  CsharpCacheBuildModeNone = "csharp_cache_bmn",
-  CsharpNewCacheKey = "csharp_new_cache_key",
-  DiffInformedQueries = "diff_informed_queries",
-  DisableCsharpBuildless = "disable_csharp_buildless",
-  DisableJavaBuildlessEnabled = "disable_java_buildless_enabled",
-  DisableKotlinAnalysisEnabled = "disable_kotlin_analysis_enabled",
-  ExportDiagnosticsEnabled = "export_diagnostics_enabled",
-  /**
-   * Emergency override that forces the CodeQL CLI to use the JGit-based Git backend instead of its
-   * default backend selection.
-   */
-  ForceJGit = "force_jgit",
-  ForceNightly = "force_nightly",
-  IgnoreGeneratedFiles = "ignore_generated_files",
-  JavaNetworkDebugging = "java_network_debugging",
-  OverlayAnalysis = "overlay_analysis",
-  OverlayAnalysisCodeScanningCpp = "overlay_analysis_code_scanning_cpp",
-  OverlayAnalysisCodeScanningCsharp = "overlay_analysis_code_scanning_csharp",
-  OverlayAnalysisCodeScanningGo = "overlay_analysis_code_scanning_go",
-  OverlayAnalysisCodeScanningJava = "overlay_analysis_code_scanning_java",
-  OverlayAnalysisCodeScanningJavascript = "overlay_analysis_code_scanning_javascript",
-  OverlayAnalysisCodeScanningPython = "overlay_analysis_code_scanning_python",
-  OverlayAnalysisCodeScanningRuby = "overlay_analysis_code_scanning_ruby",
-  OverlayAnalysisCpp = "overlay_analysis_cpp",
-  OverlayAnalysisCsharp = "overlay_analysis_csharp",
-  OverlayAnalysisGo = "overlay_analysis_go",
-  OverlayAnalysisJava = "overlay_analysis_java",
-  OverlayAnalysisJavascript = "overlay_analysis_javascript",
-  /**
-   * Lowers the overlay minimum available disk space to 8 GB. The lowest enabled limit wins; if
-   * none are enabled, the default applies.
-   */
-  OverlayAnalysisMinDisk8Gb = "overlay_analysis_min_disk_8_gb",
-  /**
-   * Lowers the overlay minimum available disk space to 9 GB. The lowest enabled limit wins; if
-   * none are enabled, the default applies.
-   */
-  OverlayAnalysisMinDisk9Gb = "overlay_analysis_min_disk_9_gb",
-  /**
-   * Lowers the overlay minimum available disk space to 10 GB. The lowest enabled limit wins; if
-   * none are enabled, the default applies.
-   */
-  OverlayAnalysisMinDisk10Gb = "overlay_analysis_min_disk_10_gb",
-  /**
-   * Lowers the overlay minimum available disk space to 11 GB. The lowest enabled limit wins; if
-   * none are enabled, the default applies.
-   */
-  OverlayAnalysisMinDisk11Gb = "overlay_analysis_min_disk_11_gb",
-  /**
-   * Lowers the overlay minimum available disk space to 12 GB. The lowest enabled limit wins; if
-   * none are enabled, the default applies.
-   */
-  OverlayAnalysisMinDisk12Gb = "overlay_analysis_min_disk_12_gb",
-  /**
-   * Lowers the overlay minimum available disk space to 13 GB. The lowest enabled limit wins; if
-   * none are enabled, the default applies.
-   */
-  OverlayAnalysisMinDisk13Gb = "overlay_analysis_min_disk_13_gb",
-  OverlayAnalysisPython = "overlay_analysis_python",
-  OverlayAnalysisRuby = "overlay_analysis_ruby",
-  /** Controls whether hardware checks are skipped for overlay analysis. */
-  OverlayAnalysisSkipResourceChecks = "overlay_analysis_skip_resource_checks",
-  /** Controls whether the Actions cache is checked for overlay build outcomes. */
-  OverlayAnalysisStatusCheck = "overlay_analysis_status_check",
-  /** Controls whether overlay build failures on the default branch are stored in the Actions cache. */
-  OverlayAnalysisStatusSave = "overlay_analysis_status_save",
-  QaTelemetryEnabled = "qa_telemetry_enabled",
-  /** Whether we should fail early if we detect that traced analysis is unsupported. */
-  AbortUnsupportedTracedAnalysis = "abort_unsupported_traced_analysis",
-  /** Routes (some) API requests through the registry proxy. */
-  ProxyApiRequests = "proxy_api_requests",
-  /** Note that this currently only disables baseline file coverage information. */
-  SkipFileCoverageOnPrs = "skip_file_coverage_on_prs",
-  StartProxyUseFeaturesRelease = "start_proxy_use_features_release",
-  /** Whether to allow the `tools` input to be specified via a repository property. */
-  ToolsRepositoryProperty = "tools_repository_property",
-  UploadOverlayDbToApi = "upload_overlay_db_to_api",
-  ValidateDbConfig = "validate_db_config",
-}
-
 export type FeatureConfig = {
   /**
    * Default value in environments where the feature flags API is not available,

src/feature-flags/features.ts

@@ -0,0 +1,100 @@
+/**
+ * Features as named by the GitHub API endpoint.
+ *
+ * Do not include the `codeql_action_` prefix as this is stripped by the API
+ * endpoint.
+ *
+ * Legacy features should end with `_enabled`.
+ */
+export enum Feature {
+  /** Allows supported properties of configuration files to be merged. */
+  AllowMergeConfigFiles = "allow_merge_config_files",
+  /** Controls whether we allow multiple values for the `analysis-kinds` input. */
+  AllowMultipleAnalysisKinds = "allow_multiple_analysis_kinds",
+  /**
+   * Whether to check for unsupported traced analysis. Primarily intended as an override to disable
+   * the check if it causes problems somehow.
+   */
+  CheckUnsupportedTracedAnalysis = "check_unsupported_traced_analysis",
+  /** Whether to allow the `config-file` input to be specified via a repository property. */
+  ConfigFileRepositoryProperty = "config_file_repository_property",
+  CppDependencyInstallation = "cpp_dependency_installation_enabled",
+  CsharpCacheBuildModeNone = "csharp_cache_bmn",
+  CsharpNewCacheKey = "csharp_new_cache_key",
+  DiffInformedQueries = "diff_informed_queries",
+  DisableCsharpBuildless = "disable_csharp_buildless",
+  DisableJavaBuildlessEnabled = "disable_java_buildless_enabled",
+  DisableKotlinAnalysisEnabled = "disable_kotlin_analysis_enabled",
+  ExportDiagnosticsEnabled = "export_diagnostics_enabled",
+  /**
+   * Emergency override that forces the CodeQL CLI to use the JGit-based Git backend instead of its
+   * default backend selection.
+   */
+  ForceJGit = "force_jgit",
+  ForceNightly = "force_nightly",
+  IgnoreGeneratedFiles = "ignore_generated_files",
+  JavaNetworkDebugging = "java_network_debugging",
+  OverlayAnalysis = "overlay_analysis",
+  OverlayAnalysisCodeScanningCpp = "overlay_analysis_code_scanning_cpp",
+  OverlayAnalysisCodeScanningCsharp = "overlay_analysis_code_scanning_csharp",
+  OverlayAnalysisCodeScanningGo = "overlay_analysis_code_scanning_go",
+  OverlayAnalysisCodeScanningJava = "overlay_analysis_code_scanning_java",
+  OverlayAnalysisCodeScanningJavascript = "overlay_analysis_code_scanning_javascript",
+  OverlayAnalysisCodeScanningPython = "overlay_analysis_code_scanning_python",
+  OverlayAnalysisCodeScanningRuby = "overlay_analysis_code_scanning_ruby",
+  OverlayAnalysisCpp = "overlay_analysis_cpp",
+  OverlayAnalysisCsharp = "overlay_analysis_csharp",
+  OverlayAnalysisGo = "overlay_analysis_go",
+  OverlayAnalysisJava = "overlay_analysis_java",
+  OverlayAnalysisJavascript = "overlay_analysis_javascript",
+  /**
+   * Lowers the overlay minimum available disk space to 8 GB. The lowest enabled limit wins; if
+   * none are enabled, the default applies.
+   */
+  OverlayAnalysisMinDisk8Gb = "overlay_analysis_min_disk_8_gb",
+  /**
+   * Lowers the overlay minimum available disk space to 9 GB. The lowest enabled limit wins; if
+   * none are enabled, the default applies.
+   */
+  OverlayAnalysisMinDisk9Gb = "overlay_analysis_min_disk_9_gb",
+  /**
+   * Lowers the overlay minimum available disk space to 10 GB. The lowest enabled limit wins; if
+   * none are enabled, the default applies.
+   */
+  OverlayAnalysisMinDisk10Gb = "overlay_analysis_min_disk_10_gb",
+  /**
+   * Lowers the overlay minimum available disk space to 11 GB. The lowest enabled limit wins; if
+   * none are enabled, the default applies.
+   */
+  OverlayAnalysisMinDisk11Gb = "overlay_analysis_min_disk_11_gb",
+  /**
+   * Lowers the overlay minimum available disk space to 12 GB. The lowest enabled limit wins; if
+   * none are enabled, the default applies.
+   */
+  OverlayAnalysisMinDisk12Gb = "overlay_analysis_min_disk_12_gb",
+  /**
+   * Lowers the overlay minimum available disk space to 13 GB. The lowest enabled limit wins; if
+   * none are enabled, the default applies.
+   */
+  OverlayAnalysisMinDisk13Gb = "overlay_analysis_min_disk_13_gb",
+  OverlayAnalysisPython = "overlay_analysis_python",
+  OverlayAnalysisRuby = "overlay_analysis_ruby",
+  /** Controls whether hardware checks are skipped for overlay analysis. */
+  OverlayAnalysisSkipResourceChecks = "overlay_analysis_skip_resource_checks",
+  /** Controls whether the Actions cache is checked for overlay build outcomes. */
+  OverlayAnalysisStatusCheck = "overlay_analysis_status_check",
+  /** Controls whether overlay build failures on the default branch are stored in the Actions cache. */
+  OverlayAnalysisStatusSave = "overlay_analysis_status_save",
+  QaTelemetryEnabled = "qa_telemetry_enabled",
+  /** Whether we should fail early if we detect that traced analysis is unsupported. */
+  AbortUnsupportedTracedAnalysis = "abort_unsupported_traced_analysis",
+  /** Routes (some) API requests through the registry proxy. */
+  ProxyApiRequests = "proxy_api_requests",
+  /** Note that this currently only disables baseline file coverage information. */
+  SkipFileCoverageOnPrs = "skip_file_coverage_on_prs",
+  StartProxyUseFeaturesRelease = "start_proxy_use_features_release",
+  /** Whether to allow the `tools` input to be specified via a repository property. */
+  ToolsRepositoryProperty = "tools_repository_property",
+  UploadOverlayDbToApi = "upload_overlay_db_to_api",
+  ValidateDbConfig = "validate_db_config",
+}

src/setup-codeql.test.ts

@@ -1821,7 +1821,8 @@ function createToolcacheEntry(
 /**
  * Stubs out the download and the diagnostic sink, then downloads the CodeQL tools.
  *
- * @returns the extraction directory and the toolcache cleanup diagnostic, if emitted.
+ * @returns the extraction directory and, if the toolcache cleanup diagnostic was emitted, the
+ * cleanup duration it reports and its other attributes.
  */
 async function runDownloadCodeQL(
   toolcacheRoot: string,
@@ -1837,6 +1838,7 @@ async function runDownloadCodeQL(
 ): Promise<{
   codeqlFolder: string;
   cleanupDiagnostic: toolsDownload.ToolcacheCleanupResult | undefined;
+  cleanupDurationMs: number | undefined;
 }> {
   stubDownloadAndExtract();
   const addDiagnostic = sinon.stub(diagnostics, "addNoLanguageDiagnostic");
@@ -1866,11 +1868,21 @@ async function runDownloadCodeQL(
     .map((call) => call.args[1])
     .find((d) => d.source?.id === "codeql-action/toolcache-bundle-cleanup");
 
-  return {
-    codeqlFolder,
-    cleanupDiagnostic: diagnostic?.attributes as
-      toolsDownload.ToolcacheCleanupResult | undefined,
-  };
+  if (diagnostic === undefined) {
+    return {
+      codeqlFolder,
+      cleanupDiagnostic: undefined,
+      cleanupDurationMs: undefined,
+    };
+  }
+
+  // The duration varies between runs, so split it out to let tests compare the other attributes
+  // exactly.
+  const { durationMs, ...cleanupDiagnostic } =
+    diagnostic.attributes as toolsDownload.ToolcacheCleanupResult & {
+      durationMs: number;
+    };
+  return { codeqlFolder, cleanupDiagnostic, cleanupDurationMs: durationMs };
 }
 
 /**
@@ -1991,6 +2003,35 @@ test.serial(
   },
 );
 
+test.serial(
+  "downloadCodeQLBundle reports the total time taken to clean up the toolcache",
+  async (t) => {
+    await withTmpDir(async (tmpDir) => {
+      setupActionsVars(tmpDir, tmpDir);
+
+      createToolcacheEntry(tmpDir, "CodeQL", CLEANUP_CLI_VERSION);
+      createToolcacheEntry(tmpDir, "CodeQL", CLEANUP_STALE_VERSION);
+
+      // Advance the clock by 1.5s each time a path is deleted, so that deleting both versions
+      // takes 3s.
+      let elapsedMs = 1000;
+      sinon.stub(performance, "now").callsFake(() => elapsedMs);
+      const rm = fs.promises.rm;
+      sinon.stub(fs.promises, "rm").callsFake(async (...args) => {
+        elapsedMs += 1500;
+        await rm(...args);
+      });
+
+      const { cleanupDurationMs } = await runDownloadCodeQL(
+        tmpDir,
+        CLEANUP_BUNDLE_VERSION,
+      );
+
+      t.is(cleanupDurationMs, 3000);
+    });
+  },
+);
+
 test.serial(
   "downloadCodeQLBundle reports no deleted versions when the toolcache has no CodeQL bundles",
   async (t) => {

src/setup-codeql.ts

@@ -814,6 +814,7 @@ async function tryDeleteToolcacheBundles({
     return;
   }
 
+  const startTime = performance.now();
   const result = await deleteToolcacheBundles({ env, logger });
 
   addNoLanguageDiagnostic(
@@ -821,7 +822,7 @@ async function tryDeleteToolcacheBundles({
     makeTelemetryDiagnostic(
       "codeql-action/toolcache-bundle-cleanup",
       "Toolcache CodeQL bundle cleanup",
-      { ...result },
+      { ...result, durationMs: util.durationMsSince(startTime) },
     ),
   );
 }

src/tools-download.ts

@@ -342,13 +342,16 @@ export async function deleteToolcacheBundles({
       const versionDirectory = path.join(toolDirectory, entry.name);
 
       try {
+        const deletionStart = performance.now();
         await fs.promises.rm(versionDirectory, {
           force: true,
           recursive: true,
         });
         deletedVersions.push(entry.name);
         logger.info(
-          `Deleted the CodeQL tools at '${versionDirectory}' from the toolcache to free up disk space.`,
+          `Deleted the CodeQL tools at '${versionDirectory}' from the toolcache to free up disk space (${formatDuration(
+            durationMsSince(deletionStart),
+          )}).`,
         );
       } catch (e) {
         failed = true;