From e31ddba6e582935da465d3f0f7f4f077a32e0ec6 Mon Sep 17 00:00:00 2001 From: Kevin Heis Date: Wed, 17 Dec 2025 14:25:42 -0800 Subject: [PATCH] Expand README for src/webhooks (#58905) Co-authored-by: Robert Sese <734194+rsese@users.noreply.github.com> --- src/webhooks/README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/src/webhooks/README.md b/src/webhooks/README.md index b1ea2db302..fc33b14a1c 100644 --- a/src/webhooks/README.md +++ b/src/webhooks/README.md @@ -57,3 +57,37 @@ 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. + +## Ownership & Escalation + +### Ownership +- **Team**: Docs Engineering +- **Source data**: API Platform (github/rest-api-description) + +### Escalation path +1. **Pipeline failures** → #docs-engineering Slack +2. **OpenAPI schema issues** → #api-platform Slack +3. **Production incidents** → #docs-engineering + +### On-call procedures +If the webhooks pipeline fails: +1. Check workflow logs in `.github/workflows/sync-openapi.yml` +2. Verify access to `github/rest-api-description` repo +3. Check for OpenAPI schema validation errors +4. Review changes in generated data files +5. Check `config.json` SHA tracking +6. Escalate to API Platform team if schema issue + +### Monitoring +- Pipeline runs automatically on daily schedule (shared with REST/GitHub Apps) +- PRs created with `github-openapi-bot` label +- SHA tracking in `config.json` for version history +- Failures visible in GitHub Actions + +This pipeline is in maintenance mode. We will continue to support ongoing improvements incoming from the platform but we are not expecting new functionality moving forward. + +### Known limitations +- **Shared pipeline** - Cannot run webhooks independently of REST/GitHub Apps +- **Single page** - All events on one page (may impact performance) +- **Introduction placement** - Manual content must be at start of file +- **Payload complexity** - Some payloads are very large and complex