How can I use OpenAPI overlays to automate changes in a CI/CD pipeline?

How can I use OpenAPI overlays to automate changes in a CI/CD pipeline? #

Applying an overlay manually on a developer’s laptop works for a quick experiment, but the real value of the OpenAPI Overlay Specification comes from automating it: every time the canonical OpenAPI document changes, every derived output (public docs, SDKs, partner-specific specs) should be regenerated consistently, without anyone needing to remember to run a command by hand.

A Typical Pipeline Shape #

Lint and validate the base OpenAPI document.
Apply one or more overlays to produce derived documents.
Validate each derived document independently.
Publish or distribute each derived document to its destination (docs portal, SDK generator, partner delivery).

Example GitHub Actions Workflow #

name: openapi-overlays

on:
  push:
    branches: [main]
    paths:
      - 'openapi.yaml'
      - 'overlays/**'

jobs:
  apply-overlays:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Redocly CLI
        run: npm install -g @redocly/cli

      - name: Lint base document
        run: redocly lint openapi.yaml

      - name: Apply public overlay
        run: redocly join openapi.yaml --overlay overlays/public.yaml -o dist/openapi.public.yaml

      - name: Apply partner overlay
        run: redocly join openapi.yaml --overlay overlays/partner.yaml -o dist/openapi.partner.yaml

      - name: Lint derived documents
        run: |
          redocly lint dist/openapi.public.yaml
          redocly lint dist/openapi.partner.yaml          

      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: openapi-derived-documents
          path: dist/

Failing the Build on Unexpected Drift #

A useful safeguard is to fail the pipeline if applying an overlay produces an empty diff compared to the previous run when a real change to the base document was expected — this can catch cases where a JSONPath target no longer matches anything because the underlying structure changed (for example, a path was renamed and the overlay’s target silently stopped matching).

redocly join openapi.yaml --overlay overlays/public.yaml -o /tmp/new.yaml
diff dist/openapi.public.yaml /tmp/new.yaml || echo "Overlay output changed — review before merging"

Gating Merges With Overlay Validation #

Add the overlay-application step as a required check on pull requests, not just on main, so that a broken overlay (invalid JSONPath, malformed YAML) is caught before merge rather than after deployment:

on:
  pull_request:
    paths:
      - 'openapi.yaml'
      - 'overlays/**'

Versioning Derived Outputs #

Tag each derived document’s filename or path with the commit SHA or release version so that historical outputs remain available for auditing:

redocly join openapi.yaml --overlay overlays/public.yaml -o "dist/openapi.public.${GITHUB_SHA}.yaml"

Notifying Downstream Consumers #

If partners or SDK teams consume the derived output directly, trigger a downstream pipeline or webhook once the new derived document is published, rather than relying on them to poll for changes manually.

See What is the OpenAPI Overlay Specification? for the underlying model, and How can I use OpenAPI overlays to test and validate changes before publishing? for deeper validation strategies to run inside this pipeline.

Last updated on July 16, 2026.