content/rest/ from the OpenAPI description maintained in the github/rest-api-description repository. The generated pages power the REST API reference at docs.github.com/rest.
How it works
The pipeline is triggered by thesync-openapi.yml GitHub Actions workflow. When the workflow runs, it executes npm run sync-rest, which reads the OpenAPI schema and:
- Creates new Markdown files for new endpoints
- Updates existing Markdown files when endpoints change
- Deletes Markdown files for removed endpoints
content/rest/ directory. The workflow then opens a pull request in github/docs-internal with the label github-openapi-bot so the changes can be reviewed before merging.
Shared pipeline
Thesync-openapi.yml workflow runs three pipelines together in a single pull request:
REST
Generates REST API reference pages. Entrypoint:
npm run sync-restGitHub Apps
Generates GitHub Apps permission reference pages.
Webhooks
Generates webhook event reference pages. Entrypoint:
npm run sync-webhooksTriggering the workflow
Scheduled runs
The workflow runs automatically on a daily schedule. PRs created by the workflow carry thegithub-openapi-bot label.
Triggering manually (from main)
To sync sooner than the next scheduled run, trigger the workflow manually from the Actions tab using the default input options. This pulls from the main branch of github/rest-api-description.
Triggering for an unmerged PR in rest-api-description
If you need to propagate OpenAPI changes from a pull request that has not yet merged intogithub/rest-api-description:
Enter the source branch
Provide the branch name from the unmerged pull request in
github/rest-api-description as the source branch input.Running the pipeline locally
Use local development to preview REST documentation changes before triggering the automated workflow.Clone rest-api-description inside your docs-internal directory
docs-internal working directory (not in a subdirectory).Set a GitHub token in .env
repo scopes. If you are a GitHub employee, enable SSO for the github organization on the token.Pipeline configuration
The filesrc/rest/lib/config.json controls the behavior of the REST pipeline. Edit this file to configure version mappings and index ordering.
| Property | Description |
|---|---|
api-versions | Calendar-date API versions available for each docs version |
versionMapping | Maps OpenAPI version names (from github/rest-api-description) to the short names used in docs-internal |
frontmatterDefaults | Default frontmatter values added to every generated Markdown file in content/rest/ |
targetDirectory | The directory inside content/ where generated Markdown files are written |
indexOrder | Controls the order of child directories in content/rest/index.md. Use startsWith to pin directories to the top; all other directories are appended |
sha | The commit SHA from github/rest-api-description used to generate the current data. Updated automatically on each pipeline run |
Generated files
| Path | Description |
|---|---|
src/rest/data/ | Auto-generated data files produced by the pipeline. Do not edit manually. |
content/rest/ | Auto-generated Markdown reference pages served to users. |
src/rest/lib/config.json | Pipeline configuration file. Edit to adjust version mappings and ordering. |
src/rest/scripts/update-files.ts | Entrypoint script for the REST pipeline (npm run sync-rest). |
Content team guidance
Content writers can manually edit certain parts of generated Markdown files incontent/rest/:
-
Any frontmatter except
versions— The pipeline overwritesversionson each run but does not touch other frontmatter fields. -
Introduction paragraphs — Add content above the following comment in the file:
Content below this comment is replaced on each pipeline run.
When a new Markdown file is first created by the pipeline, it receives all frontmatter properties from
frontmatterDefaults in config.json. Writers can then customize any frontmatter field except versions.Monitoring and escalation
PRs created by the automated workflow carry thegithub-openapi-bot label. The sha field in src/rest/lib/config.json tracks which commit from github/rest-api-description was used to generate the current docs, providing an audit trail.
If the pipeline fails:
Check for schema validation errors
Look for OpenAPI schema validation errors in the workflow output.
Review config.json
Check
src/rest/lib/config.json for version mapping issues, especially after a new API version is introduced.- Pipeline failures →
#docs-engineeringSlack or open an issue ingithub/docs-engineering - OpenAPI schema issues →
#api-platformSlack (API Platform team ownsgithub/rest-api-description)