Ganesh Kumar

Posted on Jun 10

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

#api #automation #githubactions #tutorial

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:

Checks out the repository
Installs Spectral
Generates a SARIF report
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.