pb33f · daveshanley · Jun 6, 2025 · Jun 6, 2025 · Jun 6, 2025 · Jun 6, 2025
diff --git a/.github/workflows/test_vacuum.yaml b/.github/workflows/test_vacuum.yaml
@@ -1,11 +1,12 @@
-# .github/workflows/test_vacuum.yaml
-name: "Lint OpenAPI Spec and Comment on PR"
+name: "Lint OpenAPI specification using vacuum"
 
 on:
   push:
     branches:
-      - feature/docker-lint
-  workflow_dispatch: {}
+      - main
+  pull_request:
+    branches:
+      - main
 
 permissions:
   contents: read
@@ -19,7 +20,8 @@ jobs:
       - name: Check out repository
         uses: actions/checkout@v3
 
-      - name: Run vacuum-lint composite action
+      - name: Run OpenAPI lint with vacuum
         uses: ./
         with:
           openapi_path: "sample-specs/burgershop.yaml"
+          github_token: ${{ secrets.GITHUB_TOKEN }}
diff --git a/README.md b/README.md
@@ -1,2 +1,67 @@
-# vacuum-action
-The official GitHub action for vacuum, OpenAPI linter
+# 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. 
+
+- 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`
+
+There are currently two properties required. 
+
+- `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.
+
+```yaml
+name: "Lint OpenAPI spec with Vacuum"
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  vacuum-lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+
+      - name: Run OpenAPI linting with vacuum
+        id: lint-step
+        uses: pb33f/vacuum-action@v1
+        with:
+          openapi_path: "path/to/your/openapi-spec.yaml"
+          # ruleset: "rules/custom-rules.yaml" << Uncomment to use a custom ruleset
+
+      # The following steps will add the vacuum report as a comment on the pull request.
+      - name: Find existing vacuum report
+        id: find-comment
+        uses: peter-evans/find-comment@v3
+        with:
+          issue-number: ${{ github.event.pull_request.number || github.event.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: '<!-- vacuum-lint-report -->'
+
+      - name: Create or update vacuum report
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          body-path: ${{ steps.lint-step.outputs.report_path }}
+          edit-mode: replace
+```
+
+To learn more about vacuum visit the [vacuum docs](https://quobix.com/vacuum/)
diff --git a/action.yml b/action.yml
@@ -9,11 +9,9 @@ inputs:
     description: "Optional ruleset file or URL for vacuum lint (e.g. 'rules/ruleset.yaml')"
     required: false
     default: ""
-
-outputs:
-  report:
-    description: "Markdown-formatted lint report from vacuum"
-    # Note: you do NOT need to repeat 'value:' here; outputs get set by steps.
+  github_token:
+    description: "GitHub token (needs write permissions on PRs to post comments)"
+    required: true
 
 runs:
   using: "composite"
@@ -22,7 +20,6 @@ runs:
       id: lint
       shell: bash
       run: |
-        # Build the Docker command
         CMD="docker run --rm \
           -v ${{ github.workspace }}:/work:ro \
           dshanley/vacuum lint \
@@ -32,21 +29,43 @@ runs:
         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.
+        #
+        REPORT_FILE="$GITHUB_WORKSPACE/vacuum-lint-report.md"
+        {
+          echo "<!-- vacuum-lint-report -->"
+          echo
+          echo "$report"
+        } > "$REPORT_FILE"
 
-        # Expose it as the action output named 'report'
-        echo "::set-output name=report::$report"
+        # Output the path so the workflow can locate it.
+        echo "report_path=vacuum-lint-report.md" >> $GITHUB_OUTPUT
+        echo "report generated\n\n ${report}"
       env:
         DOCKER_BUILDKIT: 1
 
-    - name: Create or update comment on PR
-      if: ${{ github.event_name == 'pull_request' }}
+    - name: Find existing vacuum-lint comment (if any)
+      id: find-comment
+      uses: peter-evans/find-comment@v3
+      with:
+        issue-number: ${{ github.event.pull_request.number }}
+        comment-author: 'github-actions[bot]'
+        body-includes: "<!-- vacuum-lint-report -->"
+
+
+    - name: Create or update vacuum-lint comment
+      if: always()
       uses: peter-evans/create-or-update-comment@v4
       with:
-        token: ${{ secrets.GITHUB_TOKEN }}
+        token: ${{ inputs.github_token }}
         repository: ${{ github.repository }}
         issue-number: ${{ github.event.pull_request.number }}
-        body-includes: '<!-- vacuum-lint-report -->'
-        body: |
-          <!-- vacuum-lint-report -->
-          ${{ steps.lint.outputs.report }}
-        edit-mode: replace
+        comment-id: ${{ steps.find-comment.outputs.comment-id }}
+        body-path: ${{ steps.lint.outputs.report_path }}
+        edit-mode: replace
+
+
+
+