Update upload input values and logic (#1598)

- The `upload` input to the `analyze` Action now accepts the following values:
    - `always` is the default value, which uploads the SARIF file to Code Scanning for successful and failed runs.
    - `failure-only` is recommended for customers post-processing the SARIF file before uploading it to Code Scanning. This option uploads debugging information to Code Scanning for failed runs to improve the debugging experience.
    - `never` avoids uploading the SARIF file to Code Scanning even if the code scanning run fails. This is not recommended for external users since it complicates debugging.
    - The legacy `true` and `false` options will be interpreted as `always` and `failure-only` respectively.

---------

Co-authored-by: Henry Mercer <henry.mercer@me.com>

.github/query-filter-test/action.yml

@@ -40,7 +40,7 @@ runs:
       with:
         output: ${{ runner.temp }}/results
         upload-database: false
-        upload: false
+        upload: never
       env:
         CODEQL_ACTION_TEST_MODE: "true"
     - name: Check SARIF

.github/workflows/__javascript-source-root.yml

@@ -56,7 +56,7 @@ jobs:
       with:
         upload-database: false
         skip-queries: true
-        upload: false
+        upload: never
     - name: Assert database exists
       shell: bash
       run: |

.github/workflows/__upload-ref-sha-input.yml

@@ -91,7 +91,7 @@ jobs:
         upload-database: false
         ref: refs/heads/main
         sha: 5e235361806c361d4d3f8859e3c897658025a9a2
-        upload: false
+        upload: never
     - uses: ./../action/upload-sarif
       with:
         ref: refs/heads/main

.github/workflows/__with-checkout-path.yml

@@ -103,7 +103,7 @@ jobs:
         checkout_path: x/y/z/some-path/tests/multi-language-repo
         ref: v1.1.0
         sha: 474bbf07f9247ffe1856c6a0f94aeeb10e7afee6
-        upload: false
+        upload: never
         upload-database: false
 
     - uses: ./../action/upload-sarif

.github/workflows/expected-queries-runs.yml

@@ -36,7 +36,7 @@ jobs:
       with:
         output: ${{ runner.temp }}/results
         upload-database: false
-        upload: false
+        upload: never
 
     - name: Check Sarif
       uses: ./../action/.github/check-sarif

CHANGELOG.md

@@ -7,6 +7,13 @@ No user facing changes.
 ## 2.2.8 - 22 Mar 2023
 
 - Update default CodeQL bundle version to 2.12.5. [#1585](https://github.com/github/codeql-action/pull/1585)
+- Customers post-processing the SARIF output of the `analyze` Action before uploading it to Code Scanning will benefit from an improved debugging experience. [#1598](https://github.com/github/codeql-action/pull/1598)
+  - The CodeQL Action will now upload a SARIF file with debugging information to Code Scanning on failed runs for customers using `upload: false`. Previously, this was only available for customers using the default value of the `upload` input.
+  - The `upload` input to the `analyze` Action now accepts the following values:
+    - `always` is the default value, which uploads the SARIF file to Code Scanning for successful and failed runs.
+    - `failure-only` is recommended for customers post-processing the SARIF file before uploading it to Code Scanning. This option uploads debugging information to Code Scanning for failed runs to improve the debugging experience.
+    - `never` avoids uploading the SARIF file to Code Scanning even if the code scanning run fails. This is not recommended for external users since it complicates debugging.
+    - The legacy `true` and `false` options will be interpreted as `always` and `failure-only` respectively.
 
 ## 2.2.7 - 15 Mar 2023
 

analyze/action.yml

@@ -10,10 +10,14 @@ inputs:
     required: false
     default: "../results"
   upload:
-    description: Upload the SARIF file to Code Scanning
+    description: >-
+      Upload the SARIF file to Code Scanning.
+      Defaults to 'always' which uploads the SARIF file to Code Scanning for successful and failed runs.
+      'failure-only' only uploads debugging information to Code Scanning if the workflow run fails, for users post-processing the SARIF file before uploading it to Code Scanning.
+      'never' avoids uploading the SARIF file to Code Scanning, even if the code scanning run fails. This is not recommended for external users since it complicates debugging.
     required: false
     # If changing this, make sure to update workflow.ts accordingly.
-    default: "true"
+    default: "always"
   cleanup-level:
     description: "Level of cleanup to perform on CodeQL databases at the end of the analyze step. This should either be 'none' to skip cleanup, or be a valid argument for the --mode flag of the CodeQL CLI command 'codeql database cleanup' as documented at https://codeql.github.com/docs/codeql-cli/manual/database-cleanup"
     required: false

lib/actions-util.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.printDebugLogs = exports.isAnalyzingDefaultBranch = exports.getRelativeScriptPath = exports.isRunningLocalAction = exports.workflowEventName = exports.sendStatusReport = exports.createStatusReportBase = exports.getActionVersion = exports.getActionsStatus = exports.getRef = exports.computeAutomationID = exports.getAutomationID = exports.getAnalysisKey = exports.determineMergeBaseCommitOid = exports.getCommitOid = exports.getTemporaryDirectory = exports.getOptionalInput = exports.getRequiredInput = void 0;
+exports.getUploadValue = exports.printDebugLogs = exports.isAnalyzingDefaultBranch = exports.getRelativeScriptPath = exports.isRunningLocalAction = exports.workflowEventName = exports.sendStatusReport = exports.createStatusReportBase = exports.getActionVersion = exports.getActionsStatus = exports.getRef = exports.computeAutomationID = exports.getAutomationID = exports.getAnalysisKey = exports.determineMergeBaseCommitOid = exports.getCommitOid = exports.getTemporaryDirectory = exports.getOptionalInput = exports.getRequiredInput = void 0;
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
@@ -526,4 +526,22 @@ async function printDebugLogs(config) {
     }
 }
 exports.printDebugLogs = printDebugLogs;
+// Parses the `upload` input into an `UploadKind`, converting unspecified and deprecated upload inputs appropriately.
+function getUploadValue(input) {
+    switch (input) {
+        case undefined:
+        case "true":
+        case "always":
+            return "always";
+        case "false":
+        case "failure-only":
+            return "failure-only";
+        case "never":
+            return "never";
+        default:
+            core.warning(`Unrecognized 'upload' input to 'analyze' Action: ${input}. Defaulting to 'always'.`);
+            return "always";
+    }
+}
+exports.getUploadValue = getUploadValue;
 //# sourceMappingURL=actions-util.js.map

lib/analyze-action.js

@@ -176,7 +176,8 @@ async function run() {
             dbLocations[language] = util.getCodeQLDatabasePath(config, language);
         }
         core.setOutput("db-locations", dbLocations);
-        if (runStats && actionsUtil.getRequiredInput("upload") === "true") {
+        const uploadInput = actionsUtil.getOptionalInput("upload");
+        if (runStats && actionsUtil.getUploadValue(uploadInput) === "always") {
             uploadResult = await upload_lib.uploadFromActions(outputDir, actionsUtil.getRequiredInput("checkout_path"), actionsUtil.getOptionalInput("category"), logger);
             core.setOutput("sarif-id", uploadResult.sarifID);
         }

lib/init-action-post-helper.js

@@ -54,7 +54,8 @@ async function maybeUploadFailedSarif(config, repositoryNwo, features, logger) {
     const workflow = await (0, workflow_1.getWorkflow)();
     const jobName = (0, util_1.getRequiredEnvParam)("GITHUB_JOB");
     const matrix = (0, util_1.parseMatrixInput)(actionsUtil.getRequiredInput("matrix"));
-    if ((0, workflow_1.getUploadInputOrThrow)(workflow, jobName, matrix) !== "true" ||
+    const shouldUpload = (0, workflow_1.getUploadInputOrThrow)(workflow, jobName, matrix);
+    if (!["always", "failure-only"].includes(actionsUtil.getUploadValue(shouldUpload)) ||
         (0, util_1.isInTestMode)()) {
         return { upload_failed_run_skipped_because: "SARIF upload is disabled" };
     }

lib/init-action-post-helper.js.map

@@ -1 +1 @@
-{"version":3,"file":"init-action-post-helper.js","sourceRoot":"","sources":["../src/init-action-post-helper.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init-action-post-helper.js","sourceRoot":"","sources":["../src/init-action-post-helper.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,oDAAsC;AAEtC,4DAA8C;AAC9C,qCAAqC;AACrC,iDAAmD;AACnD,mDAA6D;AAG7D,6DAAuF;AACvF,wDAA0C;AAC1C,iCAA6E;AAC7E,yCAKoB;AAWpB,SAAS,mCAAmC,CAC1C,KAAc;IAEd,OAAO;QACL,uBAAuB,EACrB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QACxD,6BAA6B,EAC3B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;KACnD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,sBAAsB,CACnC,MAAc,EACd,aAA4B,EAC5B,QAA2B,EAC3B,MAAc;IAEd,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE;QACrB,OAAO,EAAE,iCAAiC,EAAE,0BAA0B,EAAE,CAAC;KAC1E;IACD,MAAM,MAAM,GAAG,MAAM,IAAA,kBAAS,EAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,uBAAO,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC,EAAE;QACxE,OAAO,EAAE,iCAAiC,EAAE,kBAAkB,EAAE,CAAC;KAClE;IACD,MAAM,QAAQ,GAAG,MAAM,IAAA,sBAAW,GAAE,CAAC;IACrC,MAAM,OAAO,GAAG,IAAA,0BAAmB,EAAC,YAAY,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,IAAA,uBAAgB,EAAC,WAAW,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxE,MAAM,YAAY,GAAG,IAAA,gCAAqB,EAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACtE,IACE,CAAC,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,QAAQ,CAClC,WAAW,CAAC,cAAc,CAAC,YAAY,CAAC,CACzC;QACD,IAAA,mBAAY,GAAE,EACd;QACA,OAAO,EAAE,iCAAiC,EAAE,0BAA0B,EAAE,CAAC;KAC1E;IACD,MAAM,QAAQ,GAAG,IAAA,kCAAuB,EAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACpE,MAAM,YAAY,GAAG,IAAA,sCAA2B,EAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC5E,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,CAAC;IAEvC,MAAM,SAAS,GAAG,4BAA4B,CAAC;IAE/C,kFAAkF;IAClF,IACE,YAAY,KAAK,SAAS;QAC1B,CAAC,CAAC,MAAM,QAAQ,CAAC,QAAQ,CAAC,uBAAO,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC,EACpE;QACA,MAAM,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;KACvE;SAAM;QACL,8EAA8E;QAC9E,MAAM,MAAM,CAAC,yBAAyB,CAAC,YAAY,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;KAC3E;IAED,IAAI,CAAC,IAAI,CAAC,+BAA+B,SAAS,EAAE,CAAC,CAAC;IACtD,MAAM,YAAY,GAAG,MAAM,SAAS,CAAC,iBAAiB,CACpD,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,MAAM,CACP,CAAC;IACF,MAAM,SAAS,CAAC,iBAAiB,CAC/B,aAAa,EACb,YAAY,CAAC,OAAO,EACpB,MAAM,EACN,EAAE,uBAAuB,EAAE,IAAI,EAAE,CAClC,CAAC;IACF,OAAO,YAAY,EAAE,YAAY,IAAI,EAAE,CAAC;AAC1C,CAAC;AAEM,KAAK,UAAU,yBAAyB,CAC7C,MAAc,EACd,aAA4B,EAC5B,QAA2B,EAC3B,MAAc;IAEd,IAAI,OAAO,CAAC,GAAG,CAAC,oEAA+C,CAAC,KAAK,MAAM,EAAE;QAC3E,IAAI;YACF,OAAO,MAAM,sBAAsB,CACjC,MAAM,EACN,aAAa,EACb,QAAQ,EACR,MAAM,CACP,CAAC;SACH;QAAC,OAAO,CAAC,EAAE;YACV,MAAM,CAAC,KAAK,CACV,2EAA2E,CAAC,EAAE,CAC/E,CAAC;YACF,OAAO,mCAAmC,CAAC,CAAC,CAAC,CAAC;SAC/C;KACF;SAAM;QACL,OAAO;YACL,iCAAiC,EAC/B,uCAAuC;SAC1C,CAAC;KACH;AACH,CAAC;AA1BD,8DA0BC;AAEM,KAAK,UAAU,GAAG,CACvB,iCAA2C,EAC3C,uBAAiC,EACjC,cAAwB,EACxB,aAA4B,EAC5B,QAA2B,EAC3B,MAAc;IAEd,MAAM,MAAM,GAAG,MAAM,IAAA,wBAAS,EAAC,WAAW,CAAC,qBAAqB,EAAE,EAAE,MAAM,CAAC,CAAC;IAC5E,IAAI,MAAM,KAAK,SAAS,EAAE;QACxB,MAAM,CAAC,OAAO,CACZ,iGAAiG,CAClG,CAAC;QACF,OAAO;KACR;IAED,MAAM,uBAAuB,GAAG,MAAM,yBAAyB,CAC7D,MAAM,EACN,aAAa,EACb,QAAQ,EACR,MAAM,CACP,CAAC;IAEF,IAAI,uBAAuB,CAAC,iCAAiC,EAAE;QAC7D,MAAM,CAAC,KAAK,CACV,8EAA8E;YAC5E,GAAG,uBAAuB,CAAC,iCAAiC,GAAG,CAClE,CAAC;KACH;IACD,8FAA8F;IAC9F,iCAAiC;IACjC,IACE,OAAO,CAAC,GAAG,CAAC,0CAA0C,CAAC,KAAK,MAAM;QAClE,CAAC,uBAAuB,CAAC,qBAAqB,EAC9C;QACA,MAAM,IAAI,KAAK,CACb,4EAA4E;YAC1E,8BAA8B,uBAAuB,GAAG,CAC3D,CAAC;KACH;IAED,qDAAqD;IACrD,IAAI,MAAM,CAAC,SAAS,EAAE;QACpB,IAAI,CAAC,IAAI,CACP,mGAAmG,CACpG,CAAC;QACF,MAAM,iCAAiC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACxD,MAAM,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAEtC,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;KAC9B;IAED,OAAO,uBAAuB,CAAC;AACjC,CAAC;AArDD,kBAqDC"}

lib/init-action-post-helper.test.js

@@ -159,7 +159,34 @@ const workflow = __importStar(require("./workflow"));
         exportDiagnosticsEnabled: true,
     });
 });
-(0, ava_1.default)("doesn't upload failed SARIF for workflow with upload: false", async (t) => {
+const UPLOAD_INPUT_TEST_CASES = [
+    {
+        uploadInput: "true",
+        shouldUpload: true,
+    },
+    {
+        uploadInput: "false",
+        shouldUpload: true,
+    },
+    {
+        uploadInput: "always",
+        shouldUpload: true,
+    },
+    {
+        uploadInput: "failure-only",
+        shouldUpload: true,
+    },
+    {
+        uploadInput: "never",
+        shouldUpload: false,
+    },
+    {
+        uploadInput: "unrecognized-value",
+        shouldUpload: true,
+    },
+];
+for (const { uploadInput, shouldUpload } of UPLOAD_INPUT_TEST_CASES) {
+    (0, ava_1.default)(`does ${shouldUpload ? "" : "not "}upload failed SARIF run for workflow with upload: ${uploadInput}`, async (t) => {
         const actionsWorkflow = createTestWorkflow([
             {
                 name: "Checkout repository",
@@ -177,15 +204,19 @@ const workflow = __importStar(require("./workflow"));
                 uses: "github/codeql-action/analyze@v2",
                 with: {
                     category: "my-category",
-                upload: false,
+                    upload: uploadInput,
                 },
             },
         ]);
         const result = await testFailedSarifUpload(t, actionsWorkflow, {
-        expectUpload: false,
+            category: "my-category",
+            expectUpload: shouldUpload,
         });
+        if (!shouldUpload) {
             t.is(result.upload_failed_run_skipped_because, "SARIF upload is disabled");
+        }
     });
+}
 (0, ava_1.default)("uploading failed SARIF run succeeds when workflow uses an input with a matrix var", async (t) => {
     const actionsWorkflow = createTestWorkflow([
         {
@@ -273,7 +304,7 @@ function createTestWorkflow(steps) {
         },
     };
 }
-async function testFailedSarifUpload(t, actionsWorkflow, { category, databaseExists = true, exportDiagnosticsEnabled = false, expectUpload = true, matrix = {}, } = {}) {
+async function testFailedSarifUpload(t, actionsWorkflow, { category, databaseExists = true, expectUpload = true, exportDiagnosticsEnabled = false, matrix = {}, } = {}) {
     const config = {
         codeQLCmd: "codeql",
         debugMode: true,
@@ -312,8 +343,6 @@ async function testFailedSarifUpload(t, actionsWorkflow, { category, databaseExi
             raw_upload_size_bytes: 20,
             zipped_upload_size_bytes: 10,
         });
-    }
-    if (expectUpload) {
         if (databaseExists && exportDiagnosticsEnabled) {
             t.true(databaseExportDiagnosticsStub.calledOnceWith(config.dbLocation, sinon.match.string, category), `Actual args were: ${databaseExportDiagnosticsStub.args}`);
         }

lib/workflow.js

@@ -339,12 +339,11 @@ exports.getCategoryInputOrThrow = getCategoryInputOrThrow;
  *
  * Typically you'll want to wrap this function in a try/catch block and handle the error.
  *
- * @returns the upload input
+ * @returns the user input to upload, or undefined if input was unspecified
  * @throws an error if the upload input could not be determined
  */
 function getUploadInputOrThrow(workflow, jobName, matrixVars) {
-    return (getInputOrThrow(workflow, jobName, getAnalyzeActionName(), "upload", matrixVars) || "true" // if unspecified, upload defaults to true
+    return getInputOrThrow(workflow, jobName, getAnalyzeActionName(), "upload", matrixVars);
-    );
 }
 exports.getUploadInputOrThrow = getUploadInputOrThrow;
 /**

pr-checks/checks/javascript-source-root.yml

@@ -17,7 +17,7 @@ steps:
     with:
       upload-database: false
       skip-queries: true
-      upload: false
+      upload: never
   - name: Assert database exists
     shell: bash
     run: |

pr-checks/checks/upload-ref-sha-input.yml

@@ -14,7 +14,7 @@ steps:
       upload-database: false
       ref: 'refs/heads/main'
       sha: '5e235361806c361d4d3f8859e3c897658025a9a2'
-      upload: false
+      upload: never
   - uses: ./../action/upload-sarif
     with:
       ref: 'refs/heads/main'

pr-checks/checks/with-checkout-path.yml

@@ -29,7 +29,7 @@ steps:
       checkout_path: x/y/z/some-path/tests/multi-language-repo
       ref: v1.1.0
       sha: 474bbf07f9247ffe1856c6a0f94aeeb10e7afee6
-      upload: false
+      upload: never
       upload-database: false
 
   - uses: ./../action/upload-sarif

src/actions-util.ts

@@ -680,3 +680,25 @@ export async function printDebugLogs(config: Config) {
     walkLogFiles(logsDirectory);
   }
 }
+
+export type UploadKind = "always" | "failure-only" | "never";
+
+// Parses the `upload` input into an `UploadKind`, converting unspecified and deprecated upload inputs appropriately.
+export function getUploadValue(input: string | undefined): UploadKind {
+  switch (input) {
+    case undefined:
+    case "true":
+    case "always":
+      return "always";
+    case "false":
+    case "failure-only":
+      return "failure-only";
+    case "never":
+      return "never";
+    default:
+      core.warning(
+        `Unrecognized 'upload' input to 'analyze' Action: ${input}. Defaulting to 'always'.`
+      );
+      return "always";
+  }
+}

src/analyze-action.ts

@@ -268,8 +268,8 @@ async function run() {
       dbLocations[language] = util.getCodeQLDatabasePath(config, language);
     }
     core.setOutput("db-locations", dbLocations);
-
+    const uploadInput = actionsUtil.getOptionalInput("upload");
-    if (runStats && actionsUtil.getRequiredInput("upload") === "true") {
+    if (runStats && actionsUtil.getUploadValue(uploadInput) === "always") {
       uploadResult = await upload_lib.uploadFromActions(
         outputDir,
         actionsUtil.getRequiredInput("checkout_path"),

src/init-action-post-helper.test.ts

@@ -161,7 +161,37 @@ test("uploads failed SARIF run with database export-diagnostics if the database
   });
 });
 
-test("doesn't upload failed SARIF for workflow with upload: false", async (t) => {
+const UPLOAD_INPUT_TEST_CASES = [
+  {
+    uploadInput: "true",
+    shouldUpload: true,
+  },
+  {
+    uploadInput: "false",
+    shouldUpload: true,
+  },
+  {
+    uploadInput: "always",
+    shouldUpload: true,
+  },
+  {
+    uploadInput: "failure-only",
+    shouldUpload: true,
+  },
+  {
+    uploadInput: "never",
+    shouldUpload: false,
+  },
+  {
+    uploadInput: "unrecognized-value",
+    shouldUpload: true,
+  },
+];
+
+for (const { uploadInput, shouldUpload } of UPLOAD_INPUT_TEST_CASES) {
+  test(`does ${
+    shouldUpload ? "" : "not "
+  }upload failed SARIF run for workflow with upload: ${uploadInput}`, async (t) => {
     const actionsWorkflow = createTestWorkflow([
       {
         name: "Checkout repository",
@@ -179,15 +209,22 @@ test("doesn't upload failed SARIF for workflow with upload: false", async (t) =>
         uses: "github/codeql-action/analyze@v2",
         with: {
           category: "my-category",
-        upload: false,
+          upload: uploadInput,
         },
       },
     ]);
     const result = await testFailedSarifUpload(t, actionsWorkflow, {
-    expectUpload: false,
+      category: "my-category",
+      expectUpload: shouldUpload,
     });
-  t.is(result.upload_failed_run_skipped_because, "SARIF upload is disabled");
+    if (!shouldUpload) {
+      t.is(
+        result.upload_failed_run_skipped_because,
+        "SARIF upload is disabled"
+      );
+    }
   });
+}
 
 test("uploading failed SARIF run succeeds when workflow uses an input with a matrix var", async (t) => {
   const actionsWorkflow = createTestWorkflow([
@@ -294,14 +331,14 @@ async function testFailedSarifUpload(
   {
     category,
     databaseExists = true,
-    exportDiagnosticsEnabled = false,
     expectUpload = true,
+    exportDiagnosticsEnabled = false,
     matrix = {},
   }: {
     category?: string;
     databaseExists?: boolean;
-    exportDiagnosticsEnabled?: boolean;
     expectUpload?: boolean;
+    exportDiagnosticsEnabled?: boolean;
     matrix?: { [key: string]: string };
   } = {}
 ): Promise<initActionPostHelper.UploadFailedSarifResult> {
@@ -356,8 +393,6 @@ async function testFailedSarifUpload(
       raw_upload_size_bytes: 20,
       zipped_upload_size_bytes: 10,
     });
-  }
-  if (expectUpload) {
     if (databaseExists && exportDiagnosticsEnabled) {
       t.true(
         databaseExportDiagnosticsStub.calledOnceWith(

src/init-action-post-helper.ts

@@ -56,8 +56,11 @@ async function maybeUploadFailedSarif(
   const workflow = await getWorkflow();
   const jobName = getRequiredEnvParam("GITHUB_JOB");
   const matrix = parseMatrixInput(actionsUtil.getRequiredInput("matrix"));
+  const shouldUpload = getUploadInputOrThrow(workflow, jobName, matrix);
   if (
-    getUploadInputOrThrow(workflow, jobName, matrix) !== "true" ||
+    !["always", "failure-only"].includes(
+      actionsUtil.getUploadValue(shouldUpload)
+    ) ||
     isInTestMode()
   ) {
     return { upload_failed_run_skipped_because: "SARIF upload is disabled" };

src/workflow.ts

@@ -426,22 +426,20 @@ export function getCategoryInputOrThrow(
  *
  * Typically you'll want to wrap this function in a try/catch block and handle the error.
  *
- * @returns the upload input
+ * @returns the user input to upload, or undefined if input was unspecified
  * @throws an error if the upload input could not be determined
  */
 export function getUploadInputOrThrow(
   workflow: Workflow,
   jobName: string,
   matrixVars: { [key: string]: string } | undefined
-): string {
+): string | undefined {
-  return (
+  return getInputOrThrow(
-    getInputOrThrow(
     workflow,
     jobName,
     getAnalyzeActionName(),
     "upload",
     matrixVars
-    ) || "true" // if unspecified, upload defaults to true
   );
 }