TrueSpec GitHub Action (Early Access)

Detect OpenAPI spec drift in CI and surface breaking changes before merge. The Action sends specs to the TrueSpec reports API and writes a PR summary.

What it does

• Compares your OpenAPI spec with implementation changes.
• Flags breaking changes with clear severity.
• Produces a short PR-friendly summary.

Inputs

• spec-path (required): Path to the OpenAPI file (head), e.g. openapi.yaml.
• reports-token (required): Token for the TrueSpec reports API.
• fail-on (optional): breaking, warning, or none. Default: breaking.
• base-ref (optional): Git ref used for the base spec (defaults to PR base ref).
• repo (optional): Repo slug sent to TrueSpec (defaults to GITHUB_REPOSITORY).
• reports-url (optional): Reports API URL. Default: https://truespec-app.com/api/reports.

Usage

name: api-contract
on: [pull_request]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - uses: alessiobianchini/TrueSpecAction@v0
        with:
          spec-path: openapi.yaml
          fail-on: breaking
          reports-token: ${{ secrets.TRUESPEC_REPORTS_TOKEN }}

Outputs

• summary: Short string describing the run.
• report-id: Report ID returned by the API.

Early access

Join the waitlist to get early access to new features.

• https://truespec-app.com/#waitlist

License

MIT