GitHub's OpenAPI description is generated, which is why pull requests are refused

The repository is an artefact, and the README says so first

This repository contains OpenAPI descriptions for GitHub's REST API. The primary language is listed as unknown, because there is no program here. The only code in the repository is the lint configuration.

The reason the repository is not a hand-maintained document is the single most useful sentence in the README. Because the description is used across GitHub's whole API development experience, the project does not currently accept pull requests that directly modify the description. The repository is kept up to date automatically with the description used to validate GitHub API requests as well as powering contract tests.

That inverts the normal relationship between an API and its schema. Rather than documentation catching up with an implementation, the same artefact that describes the API is what rejects requests that violate it, and what contract tests run against. A pull request fixing a typo would be overwritten by the next generation run, and a pull request changing a schema would conflict with the enforcement layer.

So the contribution path is an issue. If you have identified a mismatch between GitHub API behaviour and the descriptions, or found an issue with the format of a schema, the README directs you to open an issue using the schema-inaccuracy template. CONTRIBUTING.md holds the detail.

The repository is not archived and the last push was on 2026-10-16.

Bundled versus dereferenced, and why you might not get a choice

Every OpenAPI document is published in two formats, and the difference is about whether your tooling can handle references.

The bundled descriptions are single file artefacts that make usages of OpenAPI components reusable and portable. This is the preferred way of interacting with GitHub's OpenAPI description. The bundled form has common schemas defined once in a components section and referenced from many operations, so a change to a shared schema propagates without duplication.

The dereferenced version exists because, as the README puts it, certain tools have poor support for references to components within the artefact. The project encourages looking into tooling that supports referenced components, but since that is not always possible, it also provides a fully dereferenced version with no references at all.

Practically, the dereferenced file will be substantially larger, because every schema is written out inline at each use. It is also the one to reach for when a generator emits a broken client or a linter reports unresolvable refs.

A third format is not available yet. The README says the repository only contains the bundled and dereferenced versions, and that a fully referenced directory structure is being looked into for easier browsing. So if your workflow expects a browsable tree of one file per schema, it does not exist today.

Two spec versions live in two folders, on different stability terms

The descriptions folder contains the OpenAPI 3.0 version of the description. The descriptions-next folder contains the 3.1 version and is subject to breaking changes on the main branch.

That split is the operational decision in this repository. Anything under descriptions can be depended on; anything under descriptions-next is a preview whose shape may change without a version bump on the API side. A consumer pinning main in a build today can see a different schema next week.

Project status is stated in terms of the 1.1.4 release: as of that release the description is considered stable and generally available. The release history goes back through v1.1.4 on 2021-12-16, v2.0.0 on 2022-09-22 and v2.1.0 on 2022-10-25. Note the version numbering does not track the OpenAPI version, so v2.1.0 being the latest release tag tells you nothing about which spec version is in which folder.

The practical rule is simple. If your generator supports 3.1 and you can absorb breakage, use descriptions-next and get the newer model. If you are feeding a tool with fixed 3.0 support, stay on descriptions.

Licence is MIT with LICENSE.md at the root, and the contact address given for questions about the repository is [email protected].

Known limitations you will hit before anything else

The README lists four limitations, and each of them corresponds to a specific thing a generated client will get wrong or miss.

Not all headers are described. The OpenAPI documents will grow to cover them over time, but today a client generated from these files will not have typed parameters or responses for some response headers, including rate limit and pagination signals.

Multi-segment path parameters are not supported by the OpenAPI specification. Certain GitHub resources use path parameters containing slashes, which no OpenAPI version can express as a single parameter. The workaround is an x-multi-segment vendor extension annotating those parameters, with the advice to URL-encode them in general.

Many operations are reachable through multiple paths, and only the most common form is described. Alias paths exist in the real API and are not in the description, so a client generated from these files knows one URL where the API accepts several.

And the referenced directory structure does not exist, as covered above.

The multi-segment case deserves emphasis because it silently changes request construction. A generator that does not know about x-multi-segment will emit a path where a literal slash separates two parameters, producing a request to a different endpoint rather than an error.

Vendor extensions carry what OpenAPI cannot

The README points to extensions.md for the vendor extensions used, on the grounds that some concepts are harder to express with standard OpenAPI components or are specific to GitHub.

The one extension named in the README is x-multi-segment, the marker for path parameters that span segments. Any tooling that consumes these descriptions needs to know about the extensions or it will generate a client that misconstructs those URLs.

That is the general pattern for vendor extensions: they are invisible to a spec-compliant validator and only meaningful to a consumer that has read the documentation. It is also why extensions.md exists as a separate file rather than being folded into the descriptions, since the descriptions themselves carry the extension keys inline.

The README's framing of OpenAPI itself is worth reading once, since it explains why GitHub bothers. It quotes the OpenAPI Specification on what the format is for: a standard, language-agnostic interface description for HTTP APIs that lets humans and computers discover and understand a service's capabilities without access to source code, additional documentation or network traffic inspection.

The line about removing guesswork in calling a service is the argument for a generated client, and it is the same argument that makes the limitations above costly: every undocumented header and every alias path is guesswork that survived.

How the repository lints itself

The build tooling in this repository is small enough to describe exactly, and it shows what the maintainers consider enforceable.

package.json declares a single script, lint, which runs `eslint descriptions/**/*.json --ext.json`. The eslintConfig extends plugin:json/recommended, so the lint pass is a JSON validation rather than a semantic check of the OpenAPI structure. The devDependencies are eslint and eslint-plugin-json, both at modest versions.

There are dependency overrides pinning brace-expansion, lodash and js-yaml to specific ranges, which is a supply-chain response rather than a feature.

On the Python side, requirements.txt was generated by pip-compile with --generate-hashes and every entry carries a sha256 hash. The file header says it is used by the linter workflow for yamllint installation with hash verification, so the yamllint configuration comes from.yamllint-config.yml and the workflow installs it reproducibly.

A.redocly.yml file is present at the repository root.

The mismatch between the two lint systems is itself informative: the JSON lint covers the descriptions folder while the YAML lint covers the repository's own configuration files.

Where hand-written types or an Octokit client fit better

Three alternatives, and the choice turns on who maintains the mapping.

A hand-written or partially handwritten client for the endpoints you use gives you exact control over pagination, rate limit handling and the alias path problem that this description does not model. The cost is that it does not stay current, and GitHub's API surface is large enough that manual maintenance becomes its own project.

Generated clients inherit the limitations above and depend on the OpenAPI version supported by the generator.

A recording-based proxy that captures real traffic and infers schemas from observation produces something closer to observed reality, since it sees the headers and alias paths this description omits. The cost is that it only knows about the traffic you recorded, so it is a complement to the description rather than a replacement.

The reasonable pattern is to treat these descriptions as the contract you generate against, and to keep the four documented limitations in mind as the places where your own code has to compensate. Contact for anything further is [email protected].

Editorial conclusion

The description fits anyone generating a typed GitHub client, running mock servers, or linting integration code against GitHub, and the dereferenced form covers tools that cannot follow component references. It does not fit anyone hoping to contribute an improvement as a pull request, because changes are not accepted, and it does not describe every path or header the API supports. Before depending on descriptions-next for anything long-lived, note that it is subject to breaking changes on the main branch, and pin to descriptions for OpenAPI 3.0 if your tooling is not ready for 3.1.

Frequently asked questions

Official sources

1. github/rest-api-description on GitHub
2. Issues
3. License: MIT
4. README
5. Releases