Lint an OpenAPI file in GitHub Actions, with each finding on its line
Last checked and updated
One job is enough: check out the repository, install Node.js, and run a linter that prints its findings as GitHub annotations. The job fails when the description has an error, and each finding becomes an annotation with its file and line. The linter here is apigit lint, which runs Spectral's OpenAPI rules offline and needs no account.
The workflow
.github/workflows/lint.yml:
name: Lint OpenAPI
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 22
- name: Lint the API description
run: npx @apigit/cli@0.8.0 lint openapi.yaml --format github-actions
Three choices in it are deliberate. The CLI version is pinned, so a new release cannot change the result of an old commit. permissions is read-only: the job needs nothing else. And --format github-actions makes the linter print GitHub's workflow commands in place of its table, one line per finding:
::error file=openapi.yaml,line=26,col=25,title=invalid-ref::'#/components/schemas/Ordr' does not exist
GitHub turns each such line into an annotation.
A failing pull request
A pull request in the test repository changes a reference to #/components/schemas/Ordr, where the schema is called Order. The lint step's log, as gh run view --log prints it (the web page shows ##[error] as "Error:"):
##[group]Run npx @apigit/cli@0.8.0 lint openapi.yaml --format github-actions
...
npm warn exec The following package was not found and will be installed: @apigit/cli@0.8.0
##[warning]Info object must have "contact" object.
##[error]'#/components/schemas/Ordr' does not exist
##[warning]Potentially unused component has been detected.
error: lint failed: findings at severity error or above
##[error]Process completed with exit code 1.
and the annotations GitHub attached to the check, each with its file and line:
| Level | Place | Rule | Message |
|---|---|---|---|
| failure | openapi.yaml, line 26 | invalid-ref | '#/components/schemas/Ordr' does not exist |
| warning | openapi.yaml, line 29 | oas3-unused-component | Potentially unused component has been detected. |
| warning | openapi.yaml, line 2 | info-contact | Info object must have "contact" object. |
| failure | the workflow | Process completed with exit code 1. |
The job ended with exit code 1 after 12 seconds, and the pull request shows the check lint as failed. With a branch protection rule that requires this check, the pull request cannot be merged. GitHub's documentation says annotations "are visible on GitHub in the Checks and Files changed tab of the pull request". The two findings about the reference are one mistake seen from both ends: finding a broken $ref.
A passing run
On the main branch, where the reference is correct, the same workflow passes and still reports the warning:
##[warning]Info object must have "contact" object.
Warnings do not fail the job by default. The whole job, including the download of the CLI, took 11 seconds.
Adjusting it
| Want | Change |
|---|---|
| Warnings fail the job too | lint openapi.yaml --format github-actions --fail-severity warn |
| Your own rules | Commit .spectral.yaml in the repository root; it is picked up. Another file: --ruleset path |
| A stricter built-in rule set | --builtin oas-best-practice or --builtin owasp-top10 |
| Several files | lint api/*.yaml lints each file. For one description split over files, bundle it first and lint the bundle: linting the root follows the references, but does not report problems inside the referenced files |
| A rule you do not want | Set it to off in .spectral.yaml (an example) |
| Results in the Security tab (code scanning) | Redirect --format sarif to a file and upload it in a following step with github/codeql-action/upload-sarif. That step needs if: always() (the lint step exits 1 on errors) and the job needs the permission security-events: write; for a private repository, code scanning requires GitHub Code Security |
| Run only when the description changes | on.pull_request.paths: ["openapi.yaml", ".spectral.yaml"]; do not combine a path filter with a required check: for a pull request that skips the workflow the check stays Pending, and the merge is blocked |
The same job elsewhere
Any CI system that can run Node.js runs the same command. --format junit writes the findings as a test report for systems that display those; --format json is for scripts.
What a linter does not catch
A lint job checks the description against rules. It does not know whether a change breaks existing clients: a removed field or a newly required parameter is valid OpenAPI. That is a second job, comparing the pull request with the main branch: catch breaking API changes in CI.