Recommend using default setup or matrixing languages

Author: henrymercer

lib/config-utils.js

@@ -9,6 +9,8 @@ import * as api from "./api-client";
 import { CachingKind, getCachingKind } from "./caching-utils";
 import { CodeQL } from "./codeql";
 import { shouldPerformDiffInformedAnalysis } from "./diff-informed-analysis-utils";
+import { DocUrl } from "./doc-url";
+import { EnvVar } from "./environment";
 import { Feature, FeatureEnablement } from "./feature-flags";
 import { Language, parseLanguage } from "./languages";
 import { Logger } from "./logging";
@@ -389,6 +391,22 @@ export async function getRawLanguages(
     .split(",")
     .map((x) => x.trim().toLowerCase())
     .filter((x) => x.length > 0);
+
+  if (
+    rawLanguages.length > 1 &&
+    process.env[EnvVar.SUPPRESS_SINGLE_LANGUAGE_PER_JOB_RECOMMENDATION] !==
+      "true"
+  ) {
+    logger.warning(
+      "For the best experience, we recommend analyzing each language within its own Actions job. " +
+        "If you do not need a highly customizable code scanning configuration, consider using default setup for code scanning. " +
+        "Otherwise, consider using a matrix to analyze each language in its own job. " +
+        // Space before period to avoid issues copying links
+        `For more information, see ${DocUrl.CONFIGURE_DEFAULT_SETUP} and ${DocUrl.ACTIONS_MATRIX} . ` +
+        `To suppress this warning, set the environment variable ${EnvVar.SUPPRESS_SINGLE_LANGUAGE_PER_JOB_RECOMMENDATION} to "true".`,
+    );
+  }
+
   let autodetected: boolean;
   if (rawLanguages.length) {
     autodetected = false;

lib/config-utils.js.map

@@ -3,8 +3,10 @@
  */
 
 export enum DocUrl {
+  ACTIONS_MATRIX = "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow",
   ASSIGNING_PERMISSIONS_TO_JOBS = "https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs",
   AUTOMATIC_BUILD_FAILED = "https://docs.github.com/en/code-security/code-scanning/troubleshooting-code-scanning/automatic-build-failed",
+  CONFIGURE_DEFAULT_SETUP = "https://docs.github.com/en/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning",
   DEFINE_ENV_VARIABLES = "https://docs.github.com/en/actions/learn-github-actions/variables#defining-environment-variables-for-a-single-workflow",
   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",

lib/doc-url.js

@@ -79,6 +79,9 @@ export enum EnvVar {
   /** Whether to suppress the warning if the current CLI will soon be unsupported. */
   SUPPRESS_DEPRECATED_SOON_WARNING = "CODEQL_ACTION_SUPPRESS_DEPRECATED_SOON_WARNING",
 
+  /** Whether to suppress the recommendation for analyzing a single language per job. */
+  SUPPRESS_SINGLE_LANGUAGE_PER_JOB_RECOMMENDATION = "CODEQL_ACTION_SUPPRESS_SINGLE_LANGUAGE_PER_JOB_RECOMMENDATION",
+
   /** Whether to disable uploading SARIF results or status reports to the GitHub API */
   TEST_MODE = "CODEQL_ACTION_TEST_MODE",