Enable a controlled switchover between CodeQL releases

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [UNRELEASED]
 
+- Improve stability when choosing the default version of CodeQL to use in code scanning workflow runs on Actions on GitHub.com [#1475](https://github.com/github/codeql-action/pull/1475).
+  - This change addresses customer reports of code scanning alerts on GitHub.com being closed and reopened during the rollout of new versions of CodeQL in the GitHub Actions [runner images](https://github.com/actions/runner-images).
+  - **No change is required for the majority of workflows**, including:
+    - Workflows on GitHub.com hosted runners using the latest version (`v2`) of the CodeQL Action.
+    - Workflows on GitHub.com hosted runners that are pinned to specific versions of the CodeQL Action from `v2.2.0` onwards.
+    - Workflows on GitHub Enterprise Server.
+  - **A change may be required** for workflows on GitHub.com hosted runners that are pinned to specific versions of the CodeQL Action before `v2.2.0` (e.g. `v2.1.32`):
+    - Previously, these workflows would obtain the latest version of CodeQL from the Actions runner image.
+    - Now, these workflows will download an older, compatible version of CodeQL from GitHub Releases. To use this older version, no change is required. To use the newest version of CodeQL, please update your workflows to reference the latest version of the CodeQL Action (`v2`).
+  - **Advanced users only**: Workflows that interact directly with the GitHub Actions runner image tool cache to find CodeQL, for example via the `@actions/tool-cache` npm package or direct access to the filesystem, should take into account the following internal layout changes:
+    - Previously, the tool cache was pre-populated with _one_ recent version of CodeQL. Now, it is pre-populated with _two_ recent versions of CodeQL.
+    - Previously, the CodeQL tools were located within the tool cache under a directory named after the release date, e.g. CodeQL 2.11.6 was located under `CodeQL/0.0.0-20221211/x64/codeql`. Now, the CodeQL tools are located under a directory named after the CodeQL CLI version number and release date, e.g. CodeQL 2.11.6 is now located under `CodeQL/2.11.6-20221211/x64/codeql`.
+
+    Where possible, we recommend downloading and managing the CodeQL CLI via the [CodeQL extension for the GitHub CLI](https://github.com/github/gh-codeql) or [GitHub Releases](https://github.com/github/codeql-cli-binaries/releases) rather than using the CodeQL tools from the runner image tool cache.
 - Python automatic dependency installation will no longer fail for projects using Poetry that specify `virtualenvs.options.no-pip = true` in their `poetry.toml`. [#1431](https://github.com/github/codeql-action/pull/1431).
 
 ## 2.1.38 - 12 Jan 2023