Open a docs follow-up when a PR merges with the needs-docs label
When a pull request tagged needs-docs gets merged, stage a GitBook draft, alert the docs channel in Slack, and link both sides so nothing slips.
Integrations
GitHub
GitBook
Slack Bot
Type
Categories
- Engineering
- Operations
Build me a code workflow that closes the docs-drift loop between engineering and our docs team. Every step is deterministic input-to-output mapping, no model calls.
Trigger: a GitHub webhook on the pull_request event. Only continue when action is closed AND the payload's pull_request.merged is true AND the pull_request.labels array contains a configurable label name (default: needs-docs). Drop everything else.
Step 1. Use GitHub Get a Pull Request with the owner, repo, and pull number from the webhook payload. Capture title, body, user.login (the author), html_url (the link back to the merged PR), and number.
Step 2. Use GitBook Create Change Request in a configurable GitBook space (expose spaceId as a workflow input). Set the subject to the PR title. Set the description to the PR body followed by a 'Source PR' line linking back to the merged PR's html_url so a writer has the source context. Capture the returned change request URL.
Step 3. Use Slack Bot Send a Message to a configurable Slack channel (default #docs-followups). Format the message in Slack mrkdwn and include the PR title, the author's GitHub handle, a link to the merged PR, and a link to the GitBook change request. Example shape: '*Docs follow-up needed*: <pr_url|PR title> by @author. Draft: <cr_url|Open in GitBook>'.
Step 4. Use GitHub Create an Issue Comment on the same PR number (the issues endpoint also covers PR comments) with a short message like 'Docs follow-up staged: <gitbook_url>'. That gives engineering a paper trail directly on the merged PR.
Workflow inputs to expose: the GitHub repository (owner/repo), the label name (default needs-docs), the GitBook spaceId, and the Slack channel id or name. Everything else flows from the webhook payload and the API responses.
What it does
- Watches your GitHub repository and reacts the moment a pull request labeled needs-docs gets merged.
- Pulls the PR title, description, and author so your docs team has the context they need to write a follow-up.
- Opens a draft change request in the GitBook space you choose, seeded with the PR description as a starting outline plus a link back to the merge.
- Posts a heads-up in your Slack docs channel with the GitBook link, PR title, and author, then comments on the merged PR so engineering knows a docs ticket is in flight.
What you’ll need
- A GitHub account with access to the repository you want to watch.
- A GitBook workspace with the space you want drafts opened in.
- A Slack workspace where the General Input bot can post to your docs follow-ups channel.
How to customize it
- Swap the label engineers use to flag PRs needing docs, for example docs-needed or docs-required.
- Point each repository at a different GitBook space so multiple product areas stay tidy.
- Change which Slack channel gets pinged, or DM a specific writer instead of a channel.
Use cases
- Notifications & Alerts
- Data Sync
