Worked-example report v1 / Delimit team / 2026-07-13

Detecting a removed parameter with an OpenAPI GitHub Action

Detect, classify the semver bump, generate the migration guide, in one merge gate.

Delimit ran over one update of the GitHub REST API OpenAPI (commit ffd9d969, parent 6aebfeb8). It removed seven query parameters from the Dependabot alerts endpoints, part of 41 breaking changes in 66 total, and the gate classified the update major and wrote the migration guide.

Why a worked example. GitHub publishes its REST API description as an OpenAPI document in a public repo, updated frequently, which makes a real removed-parameter update easy to isolate.

github/rest-api-description is public; the two commits are real.
This is not a defect report and GitHub is not a Delimit customer. The parameter removals are an intentional pagination change; we use the diff only to demonstrate detection.
Reproducible byte-for-byte (command at the end).

Detect, then classify, then guide

A pure diff tool will tell you a parameter is gone. That is the first step, not the answer. The questions a reviewer actually needs answered are: is this breaking, what semver bump does it force, and what does a consumer have to change? The merge gate does all three in one pass. Detection is table stakes; classification and the migration guide are what turn a diff into a decision.

It matters here because the removed parameters are a minority of the change. Seven parameter removals sit inside 41 breaking changes, inside 66 total. Detecting one class of change is not enough when a single update touches endpoints, fields, types, and parameters at once.

The setup

One GitHub Action on every pull request that touches the spec. It diffs against the base branch, classifies each change, recommends the semver bump, and fails the check on a breaking change.

# .github/workflows/api-merge-gate.yml
name: API merge gate
on: [pull_request]

jobs:
  delimit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: delimit-ai/delimit-action@v1
        with:
          spec: descriptions/api.github.com/api.github.com.json

Headline numbers

Total changes

Breaking

Removed parameters

Semver bump

major

The breaking set spans param_removed (7), field_removed (16), type_changed (10), param_type_changed (4), and endpoint_removed (1). Any one forces a major bump; the gate returns a hard fail (exit code 1) under the default policy.

What free Delimit detects

The removed-parameter findings, plus the rest of the breaking set and a representative additive finding so the full shape is visible.

breakingfinding F1
change type: param_removed
surface: /repos/{owner}/{repo}/dependabot/alerts:GET
The page, first, and last query parameters were removed from the repository Dependabot alerts listing. A client paginating with ?page= or the ?first=/?last= cursor arguments now sends parameters the endpoint no longer recognizes, and its pagination loop breaks. This is the recognizable core of the change: a move off the retired pagination arguments.
breakingfinding F2
change type: param_removed
surface: /orgs/{org}/dependabot/alerts:GET
The same first and last parameters were removed from the organization-level alerts listing. Org-wide security tooling that walked alerts with those arguments loses its paging inputs.
breakingfinding F3
change type: param_removed
surface: /enterprises/{enterprise}/dependabot/alerts:GET
And again on the enterprise-level listing. Seven parameter removals in total across the three Dependabot alerts surfaces, every one flagged breaking.
breakingfinding F4
change type: field_removed (16) + type_changed (10)
surface: multiple schemas
The removed parameters are not the whole story. The same update also removed 16 response fields, changed 10 declared types, changed 4 parameter types, and removed one endpoint. 41 of the 66 changes are breaking. A gate that only watched for removed paths would miss most of it.
additivefinding A1
change type: endpoint_added (10) + optional_field_added (13)
surface: multiple surfaces
The additive half: 10 new endpoints and 13 new optional fields, among others. Safe for existing clients, and exactly the kind of visible progress that draws a reviewer’s eye away from the removals.

Why a generic AI review misses it

A removed query parameter is one of the quietest breaking changes there is. It is not a deleted endpoint or a renamed field; it is the absence of an argument the endpoint used to accept. In a 66-change update with 10 new endpoints to talk about, a summarizing review rarely enumerates the seven that vanished, and it has no fixed notion of which changes force a version bump.

The gate classifies each parameter as present or removed, marks removals breaking, and rolls the change set up to a bump. Detection is deterministic, classification is deterministic, and the migration guide falls out of both.

The migration guide the gate generates

Representative head of the generated migration output for this diff:

# Migration Guide: GitHub REST API

This release contains 41 breaking change(s).
Follow the steps below to update your integration.

### Parameter Removed
Change:   Parameter removed: page from
          /repos/{owner}/{repo}/dependabot/alerts:GET
Action:   Stop sending this parameter. Move pagination to the
          supported arguments for this endpoint.

### Parameter Removed
Change:   Parameter removed: first from
          /orgs/{org}/dependabot/alerts:GET
Action:   Stop sending this parameter.

# ... remaining steps cover the other removed params,
#     removed fields, and type changes

The guide is generated from the classified diff. It turns 41 scattered breaking changes into an ordered list of consumer-side actions.

Reproduce locally

# Install the CLI
npm install -g delimit-cli

# Clone the spec repo (large; blobless clone is fine)
git clone --filter=blob:none https://github.com/github/rest-api-description
cd rest-api-description

# Extract the two commits around the update
SPEC=descriptions/api.github.com/api.github.com.json
git show 6aebfeb8:$SPEC > /tmp/old.json
git show ffd9d969:$SPEC > /tmp/new.json

# Run the merge gate
delimit lint /tmp/old.json /tmp/new.json

If your bytes differ from this report, raise it on the Delimit repo.

Free detects. Pro proves.

Free Delimit is the merge gate: it detects the removed parameters, classifies the bump, and generates the migration guide on every pull request. Install delimit-cli or add the delimit-ai/delimit-action to CI. Free for individual maintainers.

Pro turns the detection into a signed, replayable attestation: a portable record of every classified change and the recommended bump, verifiable by a reviewer or downstream consumer without rerunning the gate. Pro tier $10/month for teams.