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

> Discover how GitHub Docs auto-generates REST API reference documentation from OpenAPI specs. Learn about the three-stage pipeline and continuous syncing via GitHub Actions workflows.

- Repository: [GitHub/docs](https://github.com/github/docs)
- Tags: internals
- Published: 2026-06-01

---

**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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/actions.json), [`issues.json`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/api.github.com.2022-11-28.json) into [`fpt-2022-11-28.json`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/src/rest/lib/config.json).

### Stage 3: Automated Continuous Integration

The final stage is executed by the [`.github/workflows/sync-openapi.yml`](https://github.com/github/docs/blob/main/.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:

```bash
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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/src/rest/scripts/utils/get-openapi-schemas.ts)**: Separates REST schemas from webhook schemas
- **[`src/rest/scripts/utils/inject-models-schema.ts`](https://github.com/github/docs/blob/main/src/rest/scripts/utils/inject-models-schema.ts)**: Handles model injection for GitHub Models schema integration
- **[`src/rest/scripts/utils/update-markdown.ts`](https://github.com/github/docs/blob/main/src/rest/scripts/utils/update-markdown.ts)**: Regenerates Markdown front-matter for documentation pages
- **[`src/rest/lib/config.json`](https://github.com/github/docs/blob/main/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`](https://github.com/github/docs/blob/main/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:

```bash

# 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`](https://github.com/github/docs/blob/main/src/rest/scripts/update-files.ts):

```typescript
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:

```typescript
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`](https://github.com/github/docs/blob/main/src/rest/scripts/update-files.ts) for orchestration and [`src/rest/scripts/utils/sync.ts`](https://github.com/github/docs/blob/main/src/rest/scripts/utils/sync.ts) for data transformation
- **Daily automation** occurs through [`.github/workflows/sync-openapi.yml`](https://github.com/github/docs/blob/main/.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`](https://github.com/github/docs/blob/main/api.github.com.2022-11-28.json)) into product-specific names (e.g., [`fpt-2022-11-28.json`](https://github.com/github/docs/blob/main/fpt-2022-11-28.json)). The mapping is maintained in [`src/rest/lib/config.json`](https://github.com/github/docs/blob/main/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.