Automating OpenAPI Validation with Spectral and SARIF in GitHub Actions

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

Ganesh Kumar demonstrates an automated workflow for validating OpenAPI specifications. This system leverages the Static Analysis Results Interchange Format (SARIF) to integrate linting results directly into GitHub’s UI.

Why This Matters

Traditional CI pipelines often fail jobs and force developers to manually parse through extensive logs to find specification errors, which does not scale across multiple API definitions or complex rule sets. By shifting from log-based reporting to inline SARIF annotations, teams reduce the feedback loop and ensure consistency across security and quality tooling.

Key Insights

• Spectral is utilized as the primary OpenAPI linting tool for identifying specification mismatches (e.g., path parameter name vs placeholder).
• SARIF (Static Analysis Results Interchange Format) allows tools to export findings in a standardized format that GitHub Code Scanning can consume.
• The github/codeql-action/upload-sarif@v3 action enables the translation of static analysis files into direct PR annotations.

Working Examples

GitHub Actions workflow to install Spectral, lint an OpenAPI file, and upload a SARIF report.

.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

Command to generate a SARIF report using the Spectral CLI.

spectral lint openapi.yaml --format sarif --output results.sarif

Practical Applications

References:

• https://dev.to/ganesh-kumar/running-openapi-validation-in-github-actions-and-showing-findings-in-pull-requests-4n8i