Suggestion: CI check for API schema drift on swagger spec

[infracore]

Context

v2.15.0 introduced a proxy cache regression (#23025) that broke Docker pulls for users relying on the v2 API contract. Separately, #23059 flagged Docker v2 API access issues and #23065 noted a deprecated endpoint.

These are the kinds of changes that a schema diff in CI can catch before they ship — response structure changes, removed fields, and endpoint deprecations surfaced automatically in PR review.

Suggestion

Add an API schema check to PRs that modify api/v2.0/swagger.yaml. A single workflow file:

name: API Schema Check
on:
  pull_request:
    paths:
      - 'api/v2.0/**'
permissions:
  contents: read
  pull-requests: write
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: delimit-ai/delimit-action@v1
        with:
          spec: api/v2.0/swagger.yaml

This diffs the base branch spec against the PR and posts a comment identifying breaking vs non-breaking changes with semver classification. Advisory only — never blocks merges. Teams can upgrade to enforcement later.

The action detects 27 change types (endpoint removal, type changes, required parameter additions, enum value removals, etc.) and generates migration guidance for each breaking change.

Zero config, no API keys, runs in under 30 seconds. Live demo with 23 breaking changes.

Happy to open a PR if there's interest.

[marcusdonovan612-afk]

This looks useful, especially given the recent regressions. I like that it’s advisory-only and lightweight — feels like a good first step without adding friction to PRs. Surfacing breaking changes early would definitely help avoid surprises. Happy to take a look at a PR if you open one 👍

…

On Fri, Apr 3, 2026, 6:27 PM infracore ***@***.***> wrote: *infracore* created an issue (goharbor/harbor#23067) <#23067> Context v2.15.0 introduced a proxy cache regression (#23025 <#23025>) that broke Docker pulls for users relying on the v2 API contract. Separately, #23059 <#23059> flagged Docker v2 API access issues and #23065 <#23065> noted a deprecated endpoint. These are the kinds of changes that a schema diff in CI can catch before they ship — response structure changes, removed fields, and endpoint deprecations surfaced automatically in PR review. Suggestion Add an API schema check to PRs that modify api/v2.0/swagger.yaml. A single workflow file: name: API Schema Checkon: pull_request: paths: - 'api/v2.0/**'permissions: contents: read pull-requests: writejobs: check: runs-on: ubuntu-latest steps: - uses: ***@***.*** with: fetch-depth: 0 - uses: ***@***.*** with: spec: api/v2.0/swagger.yaml This diffs the base branch spec against the PR and posts a comment identifying breaking vs non-breaking changes with semver classification. Advisory only — never blocks merges. Teams can upgrade to enforcement later. The action detects 27 change types (endpoint removal, type changes, required parameter additions, enum value removals, etc.) and generates migration guidance for each breaking change. Zero config, no API keys, runs in under 30 seconds. Live demo with 23 breaking changes <delimit-ai/delimit-action-demo#2>. Happy to open a PR if there's interest. — Reply to this email directly, view it on GitHub <#23067>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/B7X52CJCX2OWSNPDLPK27SL4UBCGHAVCNFSM6AAAAACXMG6YBWVHI2DSMVQWIX3LMV43ASLTON2WKOZUGIYDENJWGY4DANA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[infracore]

Thanks @marcusdonovan612-afk, glad this resonates. I have the workflow file ready to go — single file, advisory only, scoped to api/v2.0/**.

Before I open the PR, would any of the core maintainers like to weigh in? Want to make sure a CI addition like this aligns with the project's existing workflow setup. Happy to adjust the config if there are preferences on where workflows live or how PR comments should be formatted.

[wy65701436]

hi, @infracore the recent proxy-cache failures are not related to the Harbor or /v2 API changes. The maintainers are actively investigating the root cause, and we’re also working with the upstream team to help narrow down the issue.

At this point, we suspect Harbor may be using a deprecated upstream API for authentication, and we’re in the process of validating the newer API. If everything checks out, we plan to include the fix in v2.15.1.

And for your idea, I believe we can add a pipeline to capture all the changes on the API.

[infracore]

Thanks for the context @wy65701436, makes sense that the recent failures are upstream auth and not the spec itself. Glad to hear there's interest in the schema check pipeline.

I'll open a PR with the workflow file. Default plan: .github/workflows/api-schema-check.yml, scoped to api/v2.0/**, advisory only. Let me know if you'd rather it live somewhere else or follow a different naming convention.

[chlins]

Thanks for the context @wy65701436, makes sense that the recent failures are upstream auth and not the spec itself. Glad to hear there's interest in the schema check pipeline.

I'll open a PR with the workflow file. Default plan: .github/workflows/api-schema-check.yml, scoped to api/v2.0/**, advisory only. Let me know if you'd rather it live somewhere else or follow a different naming convention.

@infracore Thanks, please make the PR and then we can review it.