Add status page diagnostic when overlay skipped

src/config-utils.test.ts

@@ -1015,6 +1015,7 @@ const getOverlayDatabaseModeMacro = test.macro({
     expected: {
       overlayDatabaseMode: OverlayDatabaseMode;
       useOverlayDatabaseCaching: boolean;
+      skippedDueToCachedStatus?: boolean;
     },
   ) => {
     return await withTmpDir(async (tempDir) => {
@@ -1085,7 +1086,10 @@ const getOverlayDatabaseModeMacro = test.macro({
           logger,
         );
 
-        t.deepEqual(result, expected);
+        t.deepEqual(result, {
+          skippedDueToCachedStatus: false,
+          ...expected,
+        });
       } finally {
         // Restore the original environment
         process.env = originalEnv;
@@ -1318,6 +1322,7 @@ test(
   {
     overlayDatabaseMode: OverlayDatabaseMode.None,
     useOverlayDatabaseCaching: false,
+    skippedDueToCachedStatus: true,
   },
 );
 
@@ -1337,6 +1342,7 @@ test(
   {
     overlayDatabaseMode: OverlayDatabaseMode.None,
     useOverlayDatabaseCaching: false,
+    skippedDueToCachedStatus: true,
   },
 );
 

src/config-utils.ts

@@ -27,9 +27,11 @@ import {
 } from "./config/db-config";
 import {
   addNoLanguageDiagnostic,
+  makeDiagnostic,
   makeTelemetryDiagnostic,
 } from "./diagnostics";
 import { shouldPerformDiffInformedAnalysis } from "./diff-informed-analysis-utils";
+import { DocUrl } from "./doc-url";
 import { EnvVar } from "./environment";
 import * as errorMessages from "./error-messages";
 import { Feature, FeatureEnablement } from "./feature-flags";
@@ -739,9 +741,11 @@ export async function getOverlayDatabaseMode(
 ): Promise<{
   overlayDatabaseMode: OverlayDatabaseMode;
   useOverlayDatabaseCaching: boolean;
+  skippedDueToCachedStatus: boolean;
 }> {
   let overlayDatabaseMode = OverlayDatabaseMode.None;
   let useOverlayDatabaseCaching = false;
+  let skippedDueToCachedStatus = false;
 
   const modeEnv = process.env.CODEQL_OVERLAY_DATABASE_MODE;
   // Any unrecognized CODEQL_OVERLAY_DATABASE_MODE value will be ignored and
@@ -781,6 +785,7 @@ export async function getOverlayDatabaseMode(
           "Consider running CodeQL analysis on a larger runner.",
       );
       overlayDatabaseMode = OverlayDatabaseMode.None;
+      skippedDueToCachedStatus = true;
     } else if (
       performResourceChecks &&
       !(await runnerSupportsOverlayAnalysis(diskUsage, ramInput, logger))
@@ -806,6 +811,7 @@ export async function getOverlayDatabaseMode(
   const nonOverlayAnalysis = {
     overlayDatabaseMode: OverlayDatabaseMode.None,
     useOverlayDatabaseCaching: false,
+    skippedDueToCachedStatus,
   };
 
   if (overlayDatabaseMode === OverlayDatabaseMode.None) {
@@ -870,6 +876,7 @@ export async function getOverlayDatabaseMode(
   return {
     overlayDatabaseMode,
     useOverlayDatabaseCaching,
+    skippedDueToCachedStatus,
   };
 }
 
@@ -1013,18 +1020,21 @@ export async function initConfig(
   // and queries, which in turn depends on the user config and the augmentation
   // properties. So we need to calculate the overlay database mode after the
   // rest of the config has been populated.
-  const { overlayDatabaseMode, useOverlayDatabaseCaching } =
-    await getOverlayDatabaseMode(
-      inputs.codeql,
-      inputs.features,
-      config.languages,
-      inputs.sourceRoot,
-      config.buildMode,
-      inputs.ramInput,
-      config.computedConfig,
-      gitVersion,
-      logger,
-    );
+  const {
+    overlayDatabaseMode,
+    useOverlayDatabaseCaching,
+    skippedDueToCachedStatus: overlaySkippedDueToCachedStatus,
+  } = await getOverlayDatabaseMode(
+    inputs.codeql,
+    inputs.features,
+    config.languages,
+    inputs.sourceRoot,
+    config.buildMode,
+    inputs.ramInput,
+    config.computedConfig,
+    gitVersion,
+    logger,
+  );
   logger.info(
     `Using overlay database mode: ${overlayDatabaseMode} ` +
       `${useOverlayDatabaseCaching ? "with" : "without"} caching.`,
@@ -1032,6 +1042,32 @@ export async function initConfig(
   config.overlayDatabaseMode = overlayDatabaseMode;
   config.useOverlayDatabaseCaching = useOverlayDatabaseCaching;
 
+  if (overlaySkippedDueToCachedStatus) {
+    addNoLanguageDiagnostic(
+      config,
+      makeDiagnostic(
+        "codeql-action/overlay-skipped-due-to-cached-status",
+        "Overlay analysis skipped due to cached status",
+        {
+          attributes: {
+            languages: config.languages,
+          },
+          markdownMessage:
+            `Overlay analysis was skipped because it failed previously on this runner. ` +
+            "Running CodeQL analysis on a larger runner may allow overlay analysis to run successfully.\n\n" +
+            "Overlay analysis will be automatically retried when the next version of CodeQL is released. " +
+            `You can also manually trigger a retry by [removing](${DocUrl.DELETE_ACTIONS_CACHE_ENTRIES}) \`codeql-overlay-status-*\` entries from the Actions cache.`,
+          severity: "note",
+          visibility: {
+            cliSummaryTable: true,
+            statusPage: true,
+            telemetry: true,
+          },
+        },
+      ),
+    );
+  }
+
   if (
     overlayDatabaseMode === OverlayDatabaseMode.Overlay ||
     (await shouldPerformDiffInformedAnalysis(

src/doc-url.ts

@@ -7,8 +7,9 @@ export enum DocUrl {
   AUTOMATIC_BUILD_FAILED = "https://docs.github.com/en/code-security/code-scanning/troubleshooting-code-scanning/automatic-build-failed",
   CODEQL_BUILD_MODES = "https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#codeql-build-modes",
   DEFINE_ENV_VARIABLES = "https://docs.github.com/en/actions/learn-github-actions/variables#defining-environment-variables-for-a-single-workflow",
+  DELETE_ACTIONS_CACHE_ENTRIES = "https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manage-caches#deleting-cache-entries",
   SCANNING_ON_PUSH = "https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#scanning-on-push",
   SPECIFY_BUILD_STEPS_MANUALLY = "https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages#about-specifying-build-steps-manually",
   SYSTEM_REQUIREMENTS = "https://codeql.github.com/docs/codeql-overview/system-requirements/",
-  TRACK_CODE_SCANNING_ALERTS_ACROSS_RUNS = "https://docs.github.com/en/enterprise-cloud@latest/code-security/code-scanning/integrating-with-code-scanning/sarif-support-for-code-scanning#providing-data-to-track-code-scanning-alerts-across-runs",
+  TRACK_CODE_SCANNING_ALERTS_ACROSS_RUNS = "https://docs.github.com/en/code-security/reference/code-scanning/sarif-support-for-code-scanning#data-for-preventing-duplicated-alerts",
 }