feat(ci): add copilot-setup-steps.yml for delegated CI-fix sessions (#174)

Pre-installs the pinned CodeQL CLI (via the existing install-codeql
composite action) and clones the matching codeql-cli-<version> branch
of github/codeql, so a Copilot coding agent session delegated to fix
compile/test errors from a CLI bump has everything it needs to run
`codeql pack install`/`codeql test run` itself instead of discovering
and installing the CLI through trial and error.

The github/codeql clone matters specifically for tests: several
languages' test `options` files (e.g. java/test/**/options) reference
third-party library stubs (log4j, servlet-api, etc.) via a relative
path into a sibling github/codeql checkout rather than vendoring those
stub jars into this repo - without it, codeql test run can't compile
the test snippets at all. This mirrors what ci.yml's own "Install
Packs" step already does.

Also links this from CONTRIBUTING.md's "Fix any compilation/test
errors" checklist item.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: felickz

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,56 @@
+name: "Copilot Setup Steps"
+
+# Runs in Copilot coding agent's ephemeral environment before it starts working on
+# a delegated task (e.g. fixing compile/test errors surfaced by a CodeQL CLI bump -
+# see CONTRIBUTING.md's "Updating the pinned CodeQL CLI/library version"). Without
+# this, Copilot would have to discover and install the CodeQL CLI itself, which is
+# slow/unreliable and can't happen at all for anything requiring auth.
+#
+# Also runs on workflow_dispatch/push/pull_request against this file itself, so it
+# can be validated like a normal CI check before Copilot ever relies on it.
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be named `copilot-setup-steps` or Copilot won't pick it up.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Setup CodeQL
+        id: install-codeql
+        uses: ./.github/actions/install-codeql
+
+      - name: Clone github/codeql (test stubs)
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          CODEQL_CLI_VERSION: ${{ steps.install-codeql.outputs.codeql-cli-version }}
+        run: |
+          # Several languages' test suites (see e.g. java/test/**/options,
+          # `--javac-args -cp ${testdir}/../../../../codeql/java/ql/test/stubs/...`)
+          # reference third-party library "stubs" (log4j, servlet-api, etc.) via a
+          # relative path into a sibling checkout of github/codeql, instead of
+          # vendoring those stub jars into this repo - github/codeql's own
+          # standard-library tests reuse the same stubs. Cloning the
+          # `codeql-cli-<version>` branch matching our pinned CLI version (mirroring
+          # ci.yml's own "Install Packs" step) is what makes those relative paths
+          # resolve, so `codeql test run` can actually compile the test snippets.
+          # `--depth=1`: we only need the tree at that branch tip, not its history.
+          gh repo clone github/codeql -- -b "codeql-cli-${CODEQL_CLI_VERSION}" --depth=1
+
+      # Deliberately not running `codeql pack install <lang>/...` here for every
+      # language - that's fast enough (a few seconds) for Copilot to run itself for
+      # whichever specific language pack(s) it's actually fixing, and running it
+      # for all 7 languages up front would just slow down every session regardless
+      # of what it's working on.

CONTRIBUTING.md

@@ -240,7 +240,10 @@ coding agent) in the loop for the hard part — fixing whatever the new CLI brea
      `version:` field is touched), so there's no rush, but it still needs:
      - [ ] Fix any compilation/test errors CI surfaces from upstream API changes (usually the
            hardest part, see [#124][pr-124] for an example of what this can involve). Consider
-           delegating this step to a Copilot coding agent session pointed at the PR/branch.
+           delegating this step to a Copilot coding agent session pointed at the PR/branch -
+           [`copilot-setup-steps.yml`][copilot-setup-steps-workflow] pre-installs the pinned
+           CodeQL CLI and the matching `github/codeql` test-stubs checkout so the agent can
+           actually run `codeql test run` itself instead of guessing.
      - [ ] Update the "Supported CodeQL versions" table above.
      - [ ] Review and merge.
      - [ ] Once merged, run [`update-release.yml`][update-release-workflow] as described in
@@ -385,6 +388,7 @@ Please do get in touch (privacy@github.com) if you have any questions about this
 [update-release-workflow]: ./.github/workflows/update-release.yml
 [update-codeql-version-workflow]: ./.github/workflows/update-codeql-version.yml
 [detect-codeql-release-workflow]: ./.github/workflows/detect-codeql-release.yml
+[copilot-setup-steps-workflow]: ./.github/workflows/copilot-setup-steps.yml
 [pin-codeql-library-versions-script]: ./.github/scripts/pin-codeql-library-versions.sh
 [codeql-cli-binaries]: https://github.com/github/codeql-cli-binaries/releases
 [release-config]: ./.release.yml