Webhooks and GitHub Apps

How webhook and GitHub Apps documentation is generated from the OpenAPI and other automated pipelines.

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.

Audit logs — npm run sync-audit-log

Workflow: .github/workflows/sync-audit-logs.yml

Script: src/audit-logs/scripts/sync.ts

Generates audit log event documentation. Run manually with:

npm run sync-audit-log

Secret scanning — npm run sync-secret-scanning

Workflow: .github/workflows/sync-secret-scanning.yml

Script: src/secret-scanning/scripts/sync.ts

Generates the list of supported secret scanning patterns. Run manually with:

npm run sync-secret-scanning

CodeQL CLI — npm run sync-codeql-cli

Workflow: .github/workflows/sync-codeql-cli.yml

Script: src/codeql-cli/scripts/sync.ts

Generates CodeQL CLI reference documentation. Run manually with:

npm run sync-codeql-cli

GraphQL — npm run sync-graphql

Workflow: .github/workflows/sync-graphql.yml

Script: src/graphql/scripts/sync.ts

Fetches 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

Issue	Contact
Pipeline failures	#docs-engineering Slack
OpenAPI schema errors	#api-platform Slack
Audit log / secret scanning data	Respective owning teams
General questions	github/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.