Webhooks pipeline

Our webhooks pipeline creates autogenerated webhooks documentation for docs.github.com/webhooks-and-events/webhooks/webhook-events-and-payloads from the OpenAPI stored in the open-source repository github/rest-api-description.

The pipeline is used to generate data that is used by the docs.github.com site when deployed locally, in review environments, or in production.

How does it work

A workflow is used to trigger the automation of the webhooks documentation. The workflow runs automatically on a schedule. The workflow that triggers the webhooks pipeline also triggers other automation pipelines that use the OpenAPI as the source data:

• GitHub Apps
• REST
• Webhooks

The workflow automatically creates a pull request with the changes (for all three pipelines) and the label github-openapi-bot.

The workflow runs the npm run sync-rest script, which then calls the src/webhooks/scripts/sync.ts script.

Manually running the pipeline

You will need to first wait for the OpenAPI to be merged into github/rest-api-description.

Then, you can manually sync the data used by the REST, Webhooks, and GitHub App pipelines before the scheduled daily run here. Use the default input options.

Local development

To run the webhooks pipeline locally:

1. Clone the github/rest-api-description repository inside your local docs-internal repository.
2. Set a GITHUB_TOKEN in your .env with (classic) repo scopes & enable SSO for the github org.
3. Run npm run sync-rest -- -s rest-api-description -o webhooks.

About this directory

• src/webhooks/data - The automatically generated data files created by running this pipeline.
• src/webhooks/lib - The source code used in production to display the webhook docs and configuration files edited by content and engineering team members.
  • src/webhooks/lib/config.json - A configuration file used to specify metadata about the webhooks pipeline.
• src/webhooks/scripts - The scripts and source code used run the webhooks pipeline, which updates the src/webhooks/data directory.
  • src/webhooks/scripts/sync.ts - The entrypoint script that runs the webhooks pipeline.
• src/webhooks/tests - The tests used to verify the webhooks pipeline.

Configuring the pipeline

The src/webhooks/lib/config.json file can contain any metadata needed by the content and engineering teams to configure the webhooks pipeline. The file currently only contains the following property:

• sha - The SHA of the commit in github/rest-api-description that was used to generate the data in src/webhooks/data. This value is automatically updated when the pipeline runs.

Content team

The content writers can manually update frontmatter and introductory content in the associated Markdown file content/webhooks-and-events/webhooks/webhook-events-and-payloads. Automated content gets appended to the end of the file.

How to get help

Slack: #docs-engineering Repo: github/docs-engineering

If you have a question about the webhooks pipeline, you can ask in the #docs-engineering Slack channel. If you notice a problem with the webhooks pipeline, you can open an issue in the github/docs-engineering repository.