How REST API Reference Docs Are Auto-Generated and Synced in GitHub Docs

TLDR: The GitHub Docs repository automatically generates REST API reference pages from OpenAPI specifications maintained in github/github and github/rest-api-description through a three-stage pipeline that bundles schemas, transforms them into structured JSON, and syncs via daily GitHub Actions workflows.

The REST API reference documentation on docs.github.com is not written by hand. Instead, it is programmatically generated from machine-readable OpenAPI specifications. This automation ensures that every endpoint, parameter, and response schema remains synchronized with the actual GitHub API implementation without manual intervention.

The Three-Stage Automation Pipeline

The auto-generation process consists of three distinct stages that convert raw OpenAPI specifications into publishable documentation data.

Stage 1: Bundling and Dereferencing OpenAPI Schemas

The pipeline begins by processing the OpenAPI specifications from the source repositories. When working with the github/github repository, the script executes bin/openapi bundle to produce dereferenced JSON schema files (*.deref.json) that resolve all internal references. This bundling occurs within a Docker container defined in Dockerfile.openapi_decorator when run in CI environments.

The entry point for this stage is src/rest/scripts/update-files.ts, specifically the getBundledFiles() function and bundleCommand configuration. These dereferenced files provide a flat, self-contained schema representation that eliminates circular dependencies and external references.

Stage 2: Transforming Schemas into Structured Data

Once bundled, the schemas undergo transformation in src/rest/scripts/utils/sync.ts. The syncRestData() function orchestrates this process by:

• Reading each dereferenced schema file
• Optionally injecting model definitions via injectModelsSchema for GitHub Models integration
• Parsing operations into category and sub-category structures using formatRestData()
• Writing individual JSON files per API category (e.g., actions.json, issues.json) to src/rest/data/<version>/

During this stage, normalizeDataVersionNames() rewrites filenames to match the docs-site naming convention, converting calendar-date versions like api.github.com.2022-11-28.json into fpt-2022-11-28.json. The getOpenApiSchemaFiles() utility separates REST operations from webhook schemas based on the version mapping defined in src/rest/lib/config.json.

Stage 3: Automated Continuous Integration

The final stage is executed by the .github/workflows/sync-openapi.yml GitHub Actions workflow, which runs on a daily schedule or manual dispatch. This workflow checks out three repositories—the docs repo, rest-api-description, and models-gateway—within the same workspace.

The workflow executes npm run sync-rest with specific parameters:

npm run sync-rest -- \
  --source-repos rest-api-description models-gateway \
  --output rest github-apps webhooks rest-redirects

If any generated data changed, the workflow creates a new branch named openapi-update-<SHA>, pushes it, and opens a pull request labeled github-openapi-bot for review by Docs engineers.

Core Implementation Files

The auto-generation system relies on several critical source files:

• src/rest/scripts/update-files.ts: Entry point for the entire pipeline; handles CLI arguments and orchestrates the bundling process
• src/rest/scripts/utils/sync.ts: Contains syncRestData(), formatRestData(), and the core logic for writing category-based JSON files
• src/rest/scripts/utils/get-openapi-schemas.ts: Separates REST schemas from webhook schemas
• src/rest/scripts/utils/inject-models-schema.ts: Handles model injection for GitHub Models schema integration
• src/rest/scripts/utils/update-markdown.ts: Regenerates Markdown front-matter for documentation pages
• src/rest/lib/config.json: Maintains version mappings and API version dates

Automated Cleanup and Configuration Updates

During each sync operation, the system performs maintenance tasks to ensure data consistency. Stale category files are automatically removed from src/rest/data/, and updateRestConfigData() refreshes the version-date list in src/rest/lib/config.json. The updateRestFiles() function regenerates the Markdown front-matter for all REST API reference pages, ensuring that navigation and metadata remain accurate.

Running the Sync Locally

Developers can execute the sync process locally for testing or debugging:

# Ensure you have a sibling checkout of github/github (e.g., ../github)

npm ci

# Generate data files for the REST pipeline

npm run sync-rest -- \
  --source-repos github models-gateway \
  --output rest

The --source-repos flag specifies where to obtain dereferenced OpenAPI files, while --output selects which pipelines to update (options include rest, github-apps, webhooks, and rest-redirects).

Internal Data Flow

When npm run sync-rest executes, the script performs the following operations as implemented in src/rest/scripts/update-files.ts:

if (sourceRepos.includes('github')) {
  await getBundledFiles();  // Runs `bin/openapi bundle`
}

const derefFiles = walk(sourceDirectory, { includeBasePath: true })
  .filter(f => f.endsWith('.deref.json'));

await syncRestData(
  TEMP_OPENAPI_DIR, 
  restSchemas, 
  sourceRepoDirectory, 
  injectModelsSchema
);

The syncRestData() function then structures the operations into categorized JSON files:

const formattedOperations = await formatRestData(operations);
const targetDirectoryPath = path.join(REST_DATA_DIR, versionDirectoryName);
await writeFile(
  path.join(targetDirectoryPath, `${category}.json`),
  JSON.stringify(categoryData, null, 2)
);

Summary

• The REST API reference docs are generated from OpenAPI specifications in github/github and github/rest-api-description, not written manually
• The three-stage pipeline bundles and dereferences schemas, transforms them into category-based JSON structures, and syncs via automated CI
• Key entry points include src/rest/scripts/update-files.ts for orchestration and src/rest/scripts/utils/sync.ts for data transformation
• Daily automation occurs through .github/workflows/sync-openapi.yml, which opens pull requests labeled github-openapi-bot
• Version normalization and model injection ensure the generated docs match the site's naming conventions and include GitHub Models data

Frequently Asked Questions

What source repositories feed into the REST API doc generation?

The sync process primarily consumes OpenAPI specifications from two repositories: github/github (the main GitHub codebase) and github/rest-api-description (the public REST API description repository). The models-gateway repository provides additional schema data for GitHub Models integration.

How does the system handle API versioning?

The normalizeDataVersionNames() function rewrites schema filenames to match the docs-site convention, converting calendar-date versions (e.g., api.github.com.2022-11-28.json) into product-specific names (e.g., fpt-2022-11-28.json). The mapping is maintained in src/rest/lib/config.json and updated automatically via updateRestConfigData().

Can I run the documentation sync on my local machine?

Yes. After cloning the github/docs repository and ensuring a sibling checkout of github/github exists, run npm ci to install dependencies, then execute npm run sync-rest with appropriate --source-repos and --output flags to generate the data files locally without triggering CI workflows.

What happens when the OpenAPI specifications change?

When the scheduled workflow detects changes in the source repositories, it automatically bundles the new schemas, regenerates the category JSON files, updates the configuration, removes stale files, and opens a pull request labeled github-openapi-bot. Docs engineers review and merge these PRs to publish updated API reference pages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}