add clarification about output usage hygiene

actions · Mar 19, 2024 · 218a76c · 218a76c
1 parent d78d095
commit 218a76c
Show file tree

Hide file tree

Showing 2 changed files with 15 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -83,8 +83,8 @@ Configure this action by either inlining these options in your workflow file, or
 | `retry-on-snapshot-warnings`\*         | Enable or disable retrying the action every 10 seconds while waiting for dependency submission actions to complete.                                                                                     | `true`, `false`                                                                                              | `false`       |
 | `retry-on-snapshot-warnings-timeout`\* | Maximum amount of time (in seconds) to retry the action while waiting for dependency submission actions to complete.                                                                                    | Any positive integer                                                                                         | 120           |
 | `warn-only`+                           | When set to `true`, the action will log all vulnerabilities as warnings regardless of the severity, and the action will complete with a `success` status. This overrides the `fail-on-severity` option. | `true`, `false`                                                                                              | `false`       |
-| `show-openssf-scorecard-levels`        | When set to `true`, the action will output information about all the known OpenSSF Scorecard scores for the dependencies changed in this pull request.                                                  | `true`, `false`                                                                                              | `true`        | 
-| `warn-on-openssf-scorecard-level`      | When `show-openssf-scorecard-levels` is set to `true`, this option lets you configure the threshold for when a score is considered too low and gets a :warning: warning in the CI.                      | Any positive integer                                                                                         | 3             |          
+| `show-openssf-scorecard-levels`        | When set to `true`, the action will output information about all the known OpenSSF Scorecard scores for the dependencies changed in this pull request.                                                  | `true`, `false`                                                                                              | `true`        |
+| `warn-on-openssf-scorecard-level`      | When `show-openssf-scorecard-levels` is set to `true`, this option lets you configure the threshold for when a score is considered too low and gets a :warning: warning in the CI.                      | Any positive integer                                                                                         | 3             |
 
 \*not supported for use with GitHub Enterprise Server
 
@@ -170,6 +170,17 @@ The Dependency Review GitHub Action check will only block a pull request from be
 > [!NOTE]
 > Action outputs are unicode strings [with a 1MB size limit](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#outputs-for-docker-container-and-javascript-actions).
 
+> [!IMPORTANT]
+> If you use these outputs in a run-step, you must store the ouput data in an envrioment variable instead of using the output directly. Using an output directly might break shell scripts. For example:
+>
+> ```yaml
+> env:
+>   VULNERABLE_CHANGES: ${{ steps.review.outputs.vulnerable-changes }}
+> run: echo "$VULNERABLE_CHANGES" | jq
+> ```
+>
+> instead of direct `echo '${{ steps.review.outputs.vulnerable-changes }}'`. See [examples](docs/examples.md) for more.
+
 ## Getting help
 
 If you have bug reports, questions or suggestions please [create a new issue](https://github.com/actions/dependency-review-action/issues/new/choose).

diff --git a/docs/examples.md b/docs/examples.md
@@ -193,15 +193,15 @@ jobs:
         # make sure this step runs even if the previous failed
         if: ${{ failure() && steps.review.conclusion == 'failure' }}
         shell: bash
-        env:
+        env: # store comment HTML data in an environment variable
           COMMENT: ${{ steps.review.outputs.comment-content }}
         run: | # do something with the comment:
           echo "$COMMENT"
       - name: 'List vulnerable dependencies'
         # make sure this step runs even if the previous failed
         if: ${{ failure() && steps.review.conclusion == 'failure' }}
         shell: bash
-        env:
+        env: # store JSON data in an environment variable
           VULNERABLE_CHANGES: ${{ steps.review.outputs.vulnerable-changes }}
         run: | # do something with the JSON:
           echo "$VULNERABLE_CHANGES" | jq '.[].package_url'