Running OpenAPI Validation in GitHub Actions and Showing Findings in Pull Requests

Hello, I'm Ganesh. I'm building git-lrc, an AI code reviewer that runs on every commit. It is free, unlimited, and source-available on Github. Star git-lrc on GitHub to help more developers discover the project. Do give it a try and share your feedback for improving the product.

In a previous article, I explained what SARIF is and why many security and quality tools use it as a common reporting format.

In this article, we'll focus on a practical example: validating an OpenAPI specification in GitHub Actions and displaying findings directly inside GitHub Pull Requests.

By the end, you'll have a workflow that:

• Lints your OpenAPI specification


• Generates a SARIF report


• Uploads results to GitHub Code Scanning


• Shows annotations directly in Pull Requests

Sample OpenAPI Specification

Let's start with a simple OpenAPI file that contains a deliberate issue.

openapi: 3.0.3



info:

  title: User API

  version: 1.0.0



paths:

  /users/{id}:

    get:

      operationId: getUserById



      parameters:

        - name: userId

          in: path

          required: true

          schema:

            type: string



      responses:

        "200":

          description: User found

Notice that the path is:

/users/{id}

but the parameter is named:

userId

The parameter name should match the path placeholder (id).

We'll use this mistake to verify that our workflow correctly reports findings.

Installing Spectral

For this example, we'll use Spectral, one of the most popular OpenAPI linting tools.

npm install -g @stoplight/spectral-cli

Run it locally:

spectral lint openapi.yaml

You should see an error related to the path parameter mismatch.

Generating a SARIF Report

Instead of printing results to the console, we can generate a SARIF report:

spectral lint openapi.yaml \

  --format sarif \

  --output results.sarif

This produces:

results.sarif

which GitHub can consume directly.

GitHub Actions Workflow

Create:

.github/workflows/openapi.yml

name: OpenAPI Validation



on:

  pull_request:



permissions:

  contents: read

  security-events: write



jobs:

  openapi:

    runs-on: ubuntu-latest



    steps:

      - uses: actions/checkout@v4



      - uses: actions/setup-node@v4

        with:

          node-version: 20



      - name: Install Spectral

        run: npm install -g @stoplight/spectral-cli



      - name: Generate SARIF Report

        run: |

          spectral lint openapi.yaml \

            --format sarif \

            --output results.sarif



      - name: Upload SARIF

        uses: github/codeql-action/upload-sarif@v3

        with:

          sarif_file: results.sarif

How It Works

The workflow performs four simple steps:

1. Checks out the repository


2. Installs Spectral


3. Generates a SARIF report


4. Uploads the SARIF report to GitHub

The upload step is handled by GitHub's official SARIF uploader:

- uses: github/codeql-action/upload-sarif@v3

  with:

    sarif_file: results.sarif

Once uploaded, GitHub automatically processes the findings.

Viewing Results in Pull Requests

After opening a Pull Request, GitHub analyzes the uploaded SARIF report and associates findings with the corresponding files and lines.

For our example, GitHub highlights the parameter definition and reports something similar to:

Path parameter "id" is not defined.

Expected parameter name "id" but found "userId".

Developers can review the issue directly from the Pull Request without searching through GitHub Action logs.

Why I Prefer This Approach

Many teams fail OpenAPI validation jobs and require developers to inspect CI logs.

While this works, it doesn't scale well when repositories contain multiple specifications or many validation rules.

Uploading SARIF results provides:

• Inline annotations


• Better visibility during code review


• Centralized findings in GitHub Code Scanning


• Consistent reporting across different tools

The same workflow can later be extended to include security scanners, secret scanners, IaC scanners, and custom validation tools.

Conclusion

Integrating OpenAPI validation into GitHub Actions is straightforward. With Spectral generating SARIF output and GitHub handling the presentation layer, developers receive feedback exactly where they are already reviewing code: inside the Pull Request.

If your organization already uses SARIF for other security or quality tools, OpenAPI validation can fit naturally into the same workflow with only a few lines of configuration.

Any feedback or contributors are welcome! It’s online, source-available, and ready for anyone to use.

⭐ Star git-lrc on GitHub