Skip to main content
Webhook event documentation and GitHub Apps endpoint documentation are both auto-generated from the OpenAPI stored in github/rest-api-description. They share the same sync-openapi.yml workflow as the REST pipeline, but write output to separate directories. Several other documentation types — audit logs, secret scanning, and CodeQL CLI — have their own independent sync scripts.

​
The shared OpenAPI pipeline

The .github/workflows/sync-openapi.yml workflow triggers three pipelines in a single run:

REST

Writes Markdown to content/rest/ and data to src/rest/data/

Webhooks

Writes data to src/webhooks/data/

GitHub Apps

Writes data to src/github-apps/data/
All three pipelines are triggered by npm run sync-rest. For webhooks and GitHub Apps, the script writes to different output directories using the -o flag. Automated PRs carry the github-openapi-bot label.

​
Webhooks pipeline

The webhooks pipeline generates documentation for docs.github.com/webhooks-and-events/webhooks/webhook-events-and-payloads.

​
Directory structure

src/webhooks/
├── components/    # React components for rendering webhook event pages
├── data/          # Auto-generated JSON files (do not edit manually)
├── lib/
│   └── config.json  # SHA of last synced rest-api-description commit
├── middleware/    # Express middleware for injecting webhook data
├── pages/         # Next.js page files
├── scripts/
│   └── sync.ts    # Pipeline entrypoint
└── tests/         # Vitest tests
The content file content/webhooks-and-events/webhooks/webhook-events-and-payloads can have manually authored frontmatter and an introductory paragraph. Automated content is appended after that.

​
Running locally

npm run sync-rest -- -s rest-api-description -o webhooks
Or use the dedicated script alias: 
npm run sync-webhooks

​
GitHub Apps pipeline

The GitHub Apps pipeline generates the endpoint permission tables for:
  • Endpoints available for GitHub App installation access tokens
  • Endpoints available for GitHub App user access tokens
  • Endpoints available for fine-grained personal access tokens
  • Permissions required for GitHub Apps
  • Permissions required for fine-grained personal access tokens

​
Directory structure

src/github-apps/
├── components/    # React components for endpoint/permission tables
├── data/          # Auto-generated JSON files (do not edit manually)
├── lib/
│   └── config.json  # SHA of last synced rest-api-description commit
├── pages/         # Next.js page files
├── scripts/       # Pipeline scripts
└── tests/         # Vitest tests

​
Running locally

npm run sync-rest -- -s rest-api-description -o github-apps

​
Content team guidance

Writers can update frontmatter and add an introduction paragraph in the associated Markdown file above the auto-generation comment: 
<!-- Content after this section is automatically generated -->
The versions frontmatter property is overwritten on every pipeline run.

​
Other automated documentation pipelines

Several other doc types are generated by independent sync scripts with their own workflows.
Workflow: .github/workflows/sync-audit-logs.ymlScript: src/audit-logs/scripts/sync.tsGenerates audit log event documentation. Run manually with:
npm run sync-audit-log
Workflow: .github/workflows/sync-secret-scanning.ymlScript: src/secret-scanning/scripts/sync.tsGenerates the list of supported secret scanning patterns. Run manually with:
npm run sync-secret-scanning
Workflow: .github/workflows/sync-codeql-cli.ymlScript: src/codeql-cli/scripts/sync.tsGenerates CodeQL CLI reference documentation. Run manually with:
npm run sync-codeql-cli
Workflow: .github/workflows/sync-graphql.ymlScript: src/graphql/scripts/sync.tsFetches the GraphQL schema from GitHub’s API. See GraphQL docs for details.

​
SHA tracking

Each OpenAPI-driven pipeline stores the SHA of the github/rest-api-description commit it last synced from. This is recorded in the sha field of each pipeline’s config.json:
  • src/webhooks/lib/config.json
  • src/github-apps/lib/config.json
  • src/rest/lib/config.json
This value is updated automatically when the pipeline runs and gives you a precise reference for the source of every generated file.

​
Escalation paths

IssueContact
Pipeline failures#docs-engineering Slack
OpenAPI schema errors#api-platform Slack
Audit log / secret scanning dataRespective owning teams
General questionsgithub/docs-engineering repo

​
Known limitations

  • Shared pipeline — Webhooks and GitHub Apps cannot be synced independently of each other or of REST. All three run together.
  • Single webhook page — All webhook events render on a single page, which can affect performance for large payloads.
  • Introduction placement — Writer-authored introductions must appear before automated content in the source Markdown file.

Build docs developers (and LLMs) love

Get started for freeTalk to us