Add an option to save action output to a file

README.md

@@ -1,13 +1,17 @@
 # oasdiff-action
+
 [![CI](https://github.com/oasdiff/oasdiff-action/actions/workflows/test.yaml/badge.svg)](https://github.com/oasdiff/oasdiff-action/actions)
 
 GitHub actions for comparing OpenAPI specs and detect breaking changes, based on [oasdiff](https://github.com/Tufin/oasdiff) tool
 
 ## How to use?
+
 Depending on your use case, refer below for instructions on generating reports for differences, breaking changes and changelog.
 
 ### Generate a diff report
+
 Copy and paste the following snippet into your build .yml file:
+
 ```
 - name: Running OpenAPI Spec diff action
   uses: oasdiff/oasdiff-action/diff@main
@@ -16,17 +20,20 @@ Copy and paste the following snippet into your build .yml file:
     revision: 'specs/revision.yaml'
 ```
 
-This action supports additional arguments that are converted to parameters for the `oasdiff` CLI.
+This action supports additional arguments. Most are converted to parameters for the `oasdiff` CLI.
 
-| CLI | Action input | Default |
-|--------|--------|--------|
-| --fail-on-diff | fail-on-diff | false |
-| --format | format | yaml |
-| --include-path-params | include-path-params | false |
-| --exclude-elements | exclude-elements | '' |
+| CLI                   | Action input        | Default |
+| --------------------- | ------------------- | ------- |
+| --fail-on-diff        | fail-on-diff        | false   |
+| --format              | format              | yaml    |
+| --include-path-params | include-path-params | false   |
+| --exclude-elements    | exclude-elements    | ''      |
+| N/A                   | output-to-file      | ''      |
 
 ### Check for breaking API changes, and fail if any are found
+
 Copy and paste the following snippet into your build .yml file:
+
 ```
 - name: Running OpenAPI Spec diff action
   uses: oasdiff/oasdiff-action/breaking@main
@@ -38,18 +45,21 @@ Copy and paste the following snippet into your build .yml file:
 Additional arguments:
 
 | CLI                       | Action input            | Default |
-|---------------------------|-------------------------|---------|
+| ------------------------- | ----------------------- | ------- |
 | --fail-on WARN            | fail-on-diff            | true    |
 | --include-checks          | include-checks          | csv     |
 | --include-path-params     | include-path-params     | false   |
 | --deprecation-days-beta   | deprecation-days-beta   | 31      |
 | --deprecation-days-stable | deprecation-days-stable | 180     |
 | --exclude-elements        | exclude-elements        | ''      |
+| N/A                       | output-to-file          | ''      |
 
 This action delivers a summary of breaking changes, accessible as a GitHub step output named `breaking`.
 
 ### Generate a changelog
+
 Copy and paste the following snippet into your build .yml file:
+
 ```
 - name: Running OpenAPI Spec diff action
   uses: oasdiff/oasdiff-action/changelog@main
@@ -60,7 +70,8 @@ Copy and paste the following snippet into your build .yml file:
 
 Additional arguments:
 
-| CLI | Action input | Default |
-|--------|--------|--------|
-| --include-path-params | include-path-params | false |
-| --exclude-elements    | exclude-elements    | ''    |
+| CLI                   | Action input        | Default |
+| --------------------- | ------------------- | ------- |
+| --include-path-params | include-path-params | false   |
+| --exclude-elements    | exclude-elements    | ''      |
+| N/A                   | output-to-file      | ''      |

breaking/action.yml

@@ -1,39 +1,43 @@
-name: 'Check for API breaking changes'
-description: 'Detect breaking changes'
+name: "Check for API breaking changes"
+description: "Detect breaking changes"
 inputs:
   base:
-    description: 'Path of original OpenAPI spec in YAML or JSON format'
+    description: "Path of original OpenAPI spec in YAML or JSON format"
     required: true
   revision:
-    description: 'Path of revised OpenAPI spec in YAML or JSON format'
+    description: "Path of revised OpenAPI spec in YAML or JSON format"
     required: true
   fail-on-diff:
-    description: 'Fail with exit code 1 if any breaking changes are found'
+    description: "Fail with exit code 1 if any breaking changes are found"
     required: false
-    default: 'true'
+    default: "true"
   include-checks:
-    description: 'Include any of the defined optional breaking changes checks'
+    description: "Include any of the defined optional breaking changes checks"
     required: false
   include-path-params:
-    description: 'Include path parameter names in endpoint matching'
+    description: "Include path parameter names in endpoint matching"
     required: false
-    default: 'false'
+    default: "false"
   deprecation-days-beta:
-    description: 'Consider minimum sunset period for deprecation of beta API endpoints'
+    description: "Consider minimum sunset period for deprecation of beta API endpoints"
     required: false
   deprecation-days-stable:
-    description: 'Consider minimum sunset period for deprecation of stable API endpoints'
+    description: "Consider minimum sunset period for deprecation of stable API endpoints"
     required: false
   exclude-elements:
-    description: 'Exclude certain kinds of changes'
+    description: "Exclude certain kinds of changes"
     required: false
-    default: ''
+    default: ""
+  output-to-file:
+    description: "Output to a file at the given path"
+    required: false
+    default: ""
 outputs:
   breaking:
-    description: 'Output summary of API breaking changes, encompassing both warnings and errors'
+    description: "Output summary of API breaking changes, encompassing both warnings and errors"
 runs:
-  using: 'docker'
-  image: 'Dockerfile'
+  using: "docker"
+  image: "Dockerfile"
   args:
     - ${{ inputs.base }}
     - ${{ inputs.revision }}
@@ -43,3 +47,4 @@ runs:
     - ${{ inputs.deprecation-days-beta }}
     - ${{ inputs.deprecation-days-stable }}
     - ${{ inputs.exclude-elements }}
+    - ${{ inputs.output-to-file }}

breaking/entrypoint.sh

@@ -1,6 +1,24 @@
 #!/bin/sh
 set -e
 
+write_output () {
+    local output="$1"
+    local truncate_if_needed="$2"
+    if [ -n "$output_to_file" ]; then
+        echo "$output" >> "$output-to-file"
+    fi
+    # github-action limits output to 1MB
+    # we count bytes because unicode has multibyte characters
+    if [ "$truncate_if_needed" = "true" ]; then
+        size=$(echo "$output" | wc -c)
+        if [ "$size" -ge "1000000" ]; then
+            echo "WARN: diff exceeds the 1MB limit, truncating output..." >&2
+            output=$(echo "$output" | head -c 1000000)
+        fi
+    fi 
+    echo "$output" >>"$GITHUB_OUTPUT"
+}
+
 readonly base="$1"
 readonly revision="$2"
 readonly fail_on_diff="$3"
@@ -9,6 +27,7 @@ readonly include_path_params="$5"
 readonly deprecation_days_beta="$6"
 readonly deprecation_days_stable="$7"
 readonly exclude_elements="$8"
+readonly output_to_file="$9"
 
 echo "running oasdiff breaking... base: $base, revision: $revision, fail_on_diff: $fail_on_diff, include_checks: $include_checks, include_path_params: $include_path_params, deprecation_days_beta: $deprecation_days_beta, deprecation_days_stable: $deprecation_days_stable, exclude_elements: $exclude_elements"
 
@@ -42,32 +61,25 @@ echo "flags: $flags"
 # {delimiter}
 # see: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings
 delimiter=$(cat /proc/sys/kernel/random/uuid | tr -d '-')
-echo "breaking<<$delimiter" >>$GITHUB_OUTPUT
+write_output "breaking<<$delimiter"
 
 if [ -n "$flags" ]; then
-    output=$(oasdiff breaking "$base" "$revision" $flags | head -n 1)
+    output=$(oasdiff breaking "$base" "$revision" "$flags" | head -n 1)
 else
     output=$(oasdiff breaking "$base" "$revision" | head -n 1)
 fi
 
 if [ -n "$output" ]; then
-    # github-action limits output to 1MB
-    # we count bytes because unicode has multibyte characters
-    size=$(echo "$output" | wc -c)
-    if [ "$size" -ge "1000000" ]; then
-        echo "WARN: breaking exceeds the 1MB limit, truncating output..." >&2
-        output=$(echo "$output" | head -c 1000000)
-    fi
-    echo "$output" >>$GITHUB_OUTPUT
+    write_output "$output" "true"
 else
-    echo "No breaking changes" >>$GITHUB_OUTPUT
+    write_output "No breaking changes"
 fi
 
-echo "$delimiter" >>$GITHUB_OUTPUT
+write_output "$delimiter"
 
 # *** github action step output ***
 
 # Updating GitHub Action summary with formatted output
 flags="${flags} --format githubactions"
 # Writes the summary to log and updates GitHub Action summary
-oasdiff breaking "$base" "$revision" $flags
+oasdiff breaking "$base" "$revision" "$flags"

changelog/action.yml

@@ -1,28 +1,33 @@
-name: 'OpenAPI Spec: changelog'
-description: 'Generate a changelog for OpenAPI Specification 3'
+name: "OpenAPI Spec: changelog"
+description: "Generate a changelog for OpenAPI Specification 3"
 inputs:
   base:
-    description: 'Path of original OpenAPI spec in YAML or JSON format'
+    description: "Path of original OpenAPI spec in YAML or JSON format"
     required: true
   revision:
-    description: 'Path of revised OpenAPI spec in YAML or JSON format'
+    description: "Path of revised OpenAPI spec in YAML or JSON format"
     required: true
   include-path-params:
-    description: 'Include path parameter names in endpoint matching'
+    description: "Include path parameter names in endpoint matching"
     required: false
-    default: 'false'
+    default: "false"
   exclude-elements:
-    description: 'Exclude certain kinds of changes'
+    description: "Exclude certain kinds of changes"
     required: false
-    default: ''
+    default: ""
+  output-to-file:
+    description: "Output to a file at the given path"
+    required: false
+    default: ""
 outputs:
   changelog:
-    description: 'Output summary of API changelog'
+    description: "Output summary of API changelog"
 runs:
-  using: 'docker'
-  image: 'Dockerfile'
+  using: "docker"
+  image: "Dockerfile"
   args:
     - ${{ inputs.base }}
     - ${{ inputs.revision }}
     - ${{ inputs.include-path-params }}
     - ${{ inputs.exclude-elements }}
+    - ${{ inputs.output-to-file }}

changelog/entrypoint.sh

@@ -1,10 +1,29 @@
 #!/bin/sh
 set -e
 
+write_output () {
+    local output="$1"
+    local truncate_if_needed="$2"
+    if [ -n "$output_to_file" ]; then
+        echo "$output" >> "$output-to-file"
+    fi
+    # github-action limits output to 1MB
+    # we count bytes because unicode has multibyte characters
+    if [ "$truncate_if_needed" = "true" ]; then
+        size=$(echo "$output" | wc -c)
+        if [ "$size" -ge "1000000" ]; then
+            echo "WARN: diff exceeds the 1MB limit, truncating output..." >&2
+            output=$(echo "$output" | head -c 1000000)
+        fi
+    fi 
+    echo "$output" >>"$GITHUB_OUTPUT"
+}
+
 readonly base="$1"
 readonly revision="$2"
 readonly include_path_params="$3"
 readonly exclude_elements="$4"
+readonly output_to_file="$5"
 
 echo "running oasdiff changelog base: $base, revision: $revision, include_path_params: $include_path_params, exclude_elements: $exclude_elements"
 
@@ -28,28 +47,21 @@ set -o pipefail
 # {delimiter}
 # see: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings
 delimiter=$(cat /proc/sys/kernel/random/uuid | tr -d '-')
-echo "changelog<<$delimiter" >>$GITHUB_OUTPUT
+write_output "changelog<<$delimiter"
 
 if [ -n "$flags" ]; then
-    output=$(oasdiff changelog "$base" "$revision" $flags)
+    output=$(oasdiff changelog "$base" "$revision" "$flags")
 else
     output=$(oasdiff changelog "$base" "$revision")
 fi
 
 if [ -n "$output" ]; then
-    # github-action limits output to 1MB
-    # we count bytes because unicode has multibyte characters
-    size=$(echo "$output" | wc -c)
-    if [ "$size" -ge "1000000" ]; then
-        echo "WARN: changelog exceeds the 1MB limit, truncating output..." >&2
-        output=$(echo "$output" | head -c 1000000)
-    fi
-    echo "$output" >>$GITHUB_OUTPUT
+    write_output "$output" "true"
 else
-    echo "No changelog changes" >>$GITHUB_OUTPUT
+    write_output "No changelog changes"
 fi
 
-echo "$delimiter" >>$GITHUB_OUTPUT
+write_output "$delimiter"
 
 # *** github action step output ***
 

diff/action.yml

@@ -1,38 +1,43 @@
-name: 'OpenAPI Spec: diff'
-description: 'Generate a diff report for OpenAPI Specification 3'
+name: "OpenAPI Spec: diff"
+description: "Generate a diff report for OpenAPI Specification 3"
 inputs:
   base:
-    description: 'Path of original OpenAPI spec in YAML or JSON format'
+    description: "Path of original OpenAPI spec in YAML or JSON format"
     required: true
   revision:
-    description: 'Path of revised OpenAPI spec in YAML or JSON format'
+    description: "Path of revised OpenAPI spec in YAML or JSON format"
     required: true
   format:
-    description: 'Output format'
+    description: "Output format"
     required: false
-    default: 'yaml'
+    default: "yaml"
   fail-on-diff:
-    description: 'Fail with exit code 1 if a difference is found'
+    description: "Fail with exit code 1 if a difference is found"
     required: false
-    default: 'false'
+    default: "false"
   include-path-params:
-    description: 'Include path parameter names in endpoint matching'
+    description: "Include path parameter names in endpoint matching"
     required: false
-    default: 'false'
+    default: "false"
   exclude-elements:
-    description: 'Exclude certain kinds of changes'
+    description: "Exclude certain kinds of changes"
     required: false
-    default: ''
+    default: ""
+  output-to-file:
+    description: "Output to a file at the given path"
+    required: false
+    default: ""
 outputs:
   diff:
-    description: 'Output summary of API diff'
+    description: "Output summary of API diff"
 runs:
-  using: 'docker'
-  image: 'Dockerfile'
+  using: "docker"
+  image: "Dockerfile"
   args:
     - ${{ inputs.base }}
     - ${{ inputs.revision }}
     - ${{ inputs.format }}
     - ${{ inputs.fail-on-diff }}
     - ${{ inputs.include-path-params }}
     - ${{ inputs.exclude-elements }}
+    - ${{ inputs.output-to-file }}

diff/entrypoint.sh

@@ -1,12 +1,31 @@
 #!/bin/sh
 set -e
 
+write_output () {
+    local output="$1"
+    local truncate_if_needed="$2"
+    if [ -n "$output_to_file" ]; then
+        echo "$output" >> "$output-to-file"
+    fi
+    # github-action limits output to 1MB
+    # we count bytes because unicode has multibyte characters
+    if [ "$truncate_if_needed" = "true" ]; then
+        size=$(echo "$output" | wc -c)
+        if [ "$size" -ge "1000000" ]; then
+            echo "WARN: diff exceeds the 1MB limit, truncating output..." >&2
+            output=$(echo "$output" | head -c 1000000)
+        fi
+    fi 
+    echo "$output" >>"$GITHUB_OUTPUT"
+}
+
 readonly base="$1"
 readonly revision="$2"
 readonly format="$3"
 readonly fail_on_diff="$4"
 readonly include_path_params="$5"
 readonly exclude_elements="$6"
+readonly output_to_file="$7"
 
 echo "running oasdiff diff base: $base, revision: $revision, format: $format, fail_on_diff: $fail_on_diff, include_path_params: $include_path_params, exclude_elements: $exclude_elements"
 
@@ -34,27 +53,20 @@ echo "flags: $flags"
 # {delimiter}
 # see: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#multiline-strings
 delimiter=$(cat /proc/sys/kernel/random/uuid | tr -d '-')
-echo "diff<<$delimiter" >>$GITHUB_OUTPUT
+write_output "diff<<$delimiter"
 
 set -o pipefail
 
 if [ -n "$flags" ]; then
-    output=$(oasdiff diff "$base" "$revision" $flags)
+    output=$(oasdiff diff "$base" "$revision" "$flags")
 else
     output=$(oasdiff diff "$base" "$revision")
 fi
 
 if [ -n "$output" ]; then
-    # github-action limits output to 1MB
-    # we count bytes because unicode has multibyte characters
-    size=$(echo "$output" | wc -c)
-    if [ "$size" -ge "1000000" ]; then
-        echo "WARN: diff exceeds the 1MB limit, truncating output..." >&2
-        output=$(echo "$output" | head -c $1000000)
-    fi
-    echo "$output" >>$GITHUB_OUTPUT
+    write_output "$output" "true"
 else
-    echo "No changes" >>$GITHUB_OUTPUT
+    write_output "No changes"
 fi
 
-echo "$delimiter" >>$GITHUB_OUTPUT
+write_output "$delimiter"