pb33f · daveshanley · Jun 8, 2025 · Jun 8, 2025
diff --git a/.github/workflows/test_vacuum.yaml b/.github/workflows/test_vacuum.yaml
@@ -23,5 +23,20 @@ jobs:
       - name: Run OpenAPI lint with vacuum
         uses: ./
         with:
+          show_rules: true
+          fail_on_error: true
+          minimum_score: 80
+          print_logs: false
+          openapi_path: "sample-specs/burgershop.yaml"
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run OpenAPI lint with vacuum and custom ruleset
+        uses: ./
+        with:
+          show_rules: true
+          fail_on_error: true
+          minimum_score: 80
+          print_logs: true
+          ruleset: "sample-specs/ruleset.yaml"
           openapi_path: "sample-specs/burgershop.yaml"
           github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/README.md b/README.md
@@ -1,17 +1,28 @@
 # Official vacuum OpenAPI linter GitHub Action
 
-Got an OpenAPI spec in your repository? Want to lint it with vacuum? This GitHub Action will do just that. 
+Got an **OpenAPI** spec in your repository? Want to lint it with vacuum? This GitHub Action will do just that. 
 
 - Super fast
 - Super simple
 - Super useful
 
-All you need to do is add the action to your repo via a workflow via `pb33f/vacuum-action@v1`
+All you need to do is add the action to your repo via a workflow via `pb33f/vacuum-action@v2`
 
-There are currently two properties required. 
+Here are the configurable properties you can use in your workflow:
 
-- `openapi_path` - The path to your OpenAPI spec file, relative to the root of your repository.
-- `ruleset` - (optional) The path to a custom ruleset file, relative to the root of your repository. If not provided, the default ruleset will be used.
+| Property         | Type      | Required | Description                                                                                                                    |
+|------------------|-----------|----------|--------------------------------------------------------------------------------------------------------------------------------|
+| `openapi_path`   | `string`  | **true** | The path to your OpenAPI spec file, relative to the root of your repository.                                                   |
+| `github_token`   | `string`  | **true** | The GitHub token to use for authentication. This is required to post comments on pull requests.                                |
+| `ruleset`        | `string`  | _false_  | The path to a custom ruleset file, relative to the root of your repository. If not provided, the default ruleset will be used. | 
+| `show_rules`     | `boolean` | _false_  | If set to `true`, the action will show the rules that were applied. Defaults to `false`                                        |
+| `fail_on_error`  | `boolean` | _false_  | If set to `true`, the action will fail if any errors are detected in the OpenAPI spec. Defaults to `true`                      |
+| `minimum_score`  | `number`  | _false_  | The minimum score required to not fail the check. Defaults to `70`.                                                            |
+| `print_logs`     | `boolean` | _false_  | If set to `true`, the action will print the markdown report to the runner logs. Defaults to `true`                             |
+
+---
+
+## Example Workflow
 
 ```yaml
 name: "Lint OpenAPI spec with vacuum"
@@ -37,11 +48,45 @@ jobs:
         uses: actions/checkout@v3
 
       - name: Run OpenAPI lint with vacuum
-        uses: pb33f/vacuum-action@v1
+        uses: pb33f/vacuum-action@v2
         with:
-          openapi_path: "static/wiretap/giftshop-openapi.yaml"
+          openapi_path: "specs/openapi.yaml"
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          # ruleset: "rules/custom-rules.yaml" << Uncomment to use a custom ruleset
 ```
 
-To learn more about vacuum visit the [vacuum docs](https://quobix.com/vacuum/)
+## Example Workflow with optional parameters
+
+```yaml
+name: "Lint OpenAPI spec with vacuum"
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  vacuum-lint:
+    name: Run OpenAPI linting with vacuum
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Run OpenAPI lint with vacuum
+        uses: pb33f/vacuum-action@v2
+        with:
+          openapi_path: "specs/openapi.yaml"
+          ruleset: "rulesets/vacuum-ruleset.yaml"
+          show_rules: true
+          fail_on_error: true
+          minimum_score: 90
+          print_logs: true
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+```
diff --git a/action.yml b/action.yml
@@ -5,13 +5,30 @@ inputs:
   openapi_path:
     description: "Path to the OpenAPI spec file (relative to repo root, e.g., 'specs/openapi.yaml')"
     required: true
+  show_rules:
+    description: "Show the rules that were applied (default: false)"
+    required: false
+    default: "false"
+  minimum_score:
+    description: "Minimum score required to not fail the check (default: 70%)"
+    required: false
+    default: "70"
+  fail_on_error:
+    description: "Any errors will fail the check (default: true), setting to will not fail, regardless of errors reported"
+    required: false
+    default: "true"
   ruleset:
     description: "Optional ruleset file or URL for vacuum lint (e.g. 'rules/ruleset.yaml')"
     required: false
     default: ""
   github_token:
     description: "GitHub token (needs write permissions on PRs to post comments)"
     required: true
+  print_logs:
+    description: "Print the markdown report out to runner logs (defaults to 'true')"
+    required: false
+    default: "true"
+
 
 runs:
   using: "composite"
@@ -20,29 +37,48 @@ runs:
       id: lint
       shell: bash
       run: |
-        CMD="docker run --rm \
-          -v ${{ github.workspace }}:/work:ro \
-          dshanley/vacuum lint \
-          --pipeline-output ${{ inputs.openapi_path }}"
+        args=( lint --pipeline-output "${{ inputs.openapi_path }}" )
+
+        # --min-score <value>
+        args+=( --min-score "${{ inputs.minimum_score }}" )
+
+        # --fail-severity none|error
+        if [ "${{ inputs.fail_on_error }}" = "true" ]; then
+          args+=( --fail-severity error )
+        else
+          args+=( --fail-severity none )
+        fi
+
+        # --show-rules only if show_rules == "true"
+        if [ "${{ inputs.show_rules }}" = "true" ]; then
+          args+=( --show-rules )
+        fi
+
+        # optional ruleset
         if [ -n "${{ inputs.ruleset }}" ]; then
-          CMD="$CMD --ruleset ${{ inputs.ruleset }}"
+          args+=( --ruleset "${{ inputs.ruleset }}" )
         fi
-        echo "Running: $CMD"
-        report=$($CMD)
-        #
-        # Write the full Markdown report (including our HTML comment marker) to a file.
-        # We prepend "<!-- vacuum-lint-report -->" so that downstream steps can find it.
-        #
+
+        CMD=( docker run --rm \
+               -v "$GITHUB_WORKSPACE":/work:ro \
+               dshanley/vacuum "${args[@]}" )
+
+        echo "Running: ${CMD[*]}"
+        report=$("${CMD[@]}")
+
         REPORT_FILE="$GITHUB_WORKSPACE/vacuum-lint-report.md"
         {
           echo "<!-- vacuum-lint-report -->"
           echo
           echo "$report"
         } > "$REPORT_FILE"
-
-        # Output the path so the workflow can locate it.
-        echo "report_path=vacuum-lint-report.md" >> $GITHUB_OUTPUT
-        echo "report generated\n\n ${report}"
+
+        # print logs to console if enabled
+        if [ "${{ inputs.print_logs }}" = "true" ]; then
+          cat "$REPORT_FILE"
+        fi
+
+        echo "report_path=vacuum-lint-report.md" >> "$GITHUB_OUTPUT"
       env:
         DOCKER_BUILDKIT: 1
 

diff --git a/sample-specs/ruleset.yaml b/sample-specs/ruleset.yaml
@@ -0,0 +1,5 @@
+extends: [[spectral:oas, off]]
+rules:
+  oas3-valid-schema-example: true
+  oas3-missing-example: true
+  info-contact: true