From c88fd28213189258000134d99244c6680fee420d Mon Sep 17 00:00:00 2001 From: quobix Date: Sun, 8 Jun 2025 13:33:10 -0400 Subject: [PATCH] updated action to latest and greatest --- .github/workflows/test_vacuum.yaml | 15 +++++++ README.md | 63 ++++++++++++++++++++++++---- action.yml | 66 +++++++++++++++++++++++------- sample-specs/ruleset.yaml | 5 +++ 4 files changed, 125 insertions(+), 24 deletions(-) create mode 100644 sample-specs/ruleset.yaml diff --git a/.github/workflows/test_vacuum.yaml b/.github/workflows/test_vacuum.yaml index 94fd668..e54140c 100644 --- 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 index 0b90cfd..71cc075 100644 --- 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/) \ No newline at end of file +## 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 }} +``` \ No newline at end of file diff --git a/action.yml b/action.yml index a478151..9e28469 100644 --- a/action.yml +++ b/action.yml @@ -5,6 +5,18 @@ 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 @@ -12,6 +24,11 @@ inputs: 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 + 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 "" 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 "" 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 new file mode 100644 index 0000000..90158c4 --- /dev/null +++ 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 \ No newline at end of file