Skip to content

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:

LevelPlaceRuleMessage
failureopenapi.yaml, line 26invalid-ref'#/components/schemas/Ordr' does not exist
warningopenapi.yaml, line 29oas3-unused-componentPotentially unused component has been detected.
warningopenapi.yaml, line 2info-contactInfo object must have "contact" object.
failurethe workflowProcess 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

WantChange
Warnings fail the job toolint openapi.yaml --format github-actions --fail-severity warn
Your own rulesCommit .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 fileslint 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 wantSet 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 changeson.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.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish