Review Help Center docs for every new PR to main

This recipe starts a documentation review when GitHub reports that a pull request opens against main. The agent reads the PR diff, finds affected Help Center articles, and prepares evidence-backed changes for review. It does not automatically publish the public site. The product's PR-open trigger is tied to the opened webhook action, so pushing more commits to an already open PR does not retrigger this particular flow. For a post-merge check, create a separate GitHub pull request merges flow.

Before you start

• Connect the GitHub App, make the repository available to the workspace, and confirm you can manage flows. Pick the exact owner/repo and target branch main.

• Identify the external-capable Docs space that holds the Help Center, and choose a reviewer who can apply proposals and publish articles. Internal-only Docs must not be copied into public articles without review.

• Create a custom documentation agent in Automation → Agents. Allow repository targeting, repository discovery and checkout, get_pull_request_diff, focused code search and reading, and Docs search and reading. Add Docs write access only if the repository run should make authorized draft edits. A document-targeted review run can submit a proposal for a specific existing document; do not assume the repository-targeted flow can submit proposals to arbitrary documents. Use a run approval policy appropriate for your team. Check the tool catalog and Give agents tools and skills for exact capabilities.

Create the flow

1. Open Automation → Flows → New flow → Build a custom flow. Give it a recognizable name, such as Review Help Center docs on PR open to main.

2. In When, choose GitHub pull request opens. Set repository is to the connected owner/repo and base branch is to main. Both filters must match for a run to start.

3. In then, choose Start an agent run and select your documentation agent after using. The flow decides the event and target; the agent's own tools, instructions and approvals determine what it can do.

4. In on, choose a specific repository and select the same repository. GitHub PR triggers require an explicit target. Do not use whatever triggered it here.

5. Leave branch overrides empty to use the configured defaults unless your team has tested a different base and work branch. The agent should retrieve the PR diff by number, not treat a checkout of main as the proposed change.

6. Read the Flow summary and select Create flow. Open a test PR to main in the selected repository, then inspect Recent runs or Automation → Activity. If it does not run, confirm the GitHub App webhook, repository routing, filters and agent target.

Agent instructions to adapt

On the triggering GitHub PR, use the event's repository and PR number. Verify its base branch is main. Call get_pull_request_diff for that PR and inspect the changed files. If the PR diff is unavailable, stop and report the missing context rather than substituting the current main branch. Identify customer-facing changes, then search the Help Center space for the affected feature, labels and existing articles. Read the relevant pages and source. For each affected page, return its document ID and a precise suggested edit with source evidence. If authorized to edit Docs directly, make only draft changes under the run's approval policy; otherwise leave the suggestion for a document-targeted proposal or human editor. If a new article is needed, report its proposed title, collection and outline or create a draft only if authorized. If nothing customer-facing changed, state that no update is needed. Do not publish or claim unmerged behavior is live.

The flow event carries a repository, PR number, base branch and head branch into the run context. For a repeat review after additional commits, run the agent again with the PR number, or design a separate supported event workflow. A merged-PR flow can check the final diff, but merge does not by itself prove that a release is visible to customers.

Review and publish

1. In the run transcript, verify the repository, PR number, base branch, changed files and cited code. If the diff was not read, do not approve speculative edits.

2. For each existing article, review the suggested edit against the current page. To use a proposal, start a document-targeted agent run on that page with the PR evidence and review Proposed changes before selecting Apply or Discard. If the repository run was explicitly authorized to make draft edits directly, review its document diff and version history instead. If the page changed since the suggestion or proposal, generate a fresh edit from the current version.

3. Create or review a draft for missing coverage. Check its collection, links, terminology and whether it describes a released feature. Keep unshipped changes in Docs until publication is appropriate.

4. When the behavior is available to customers, publish or republish each accepted Help Center article. Docs changes alone do not update the public snapshot. Open the public URL and check the rendered instructions, links and media.

Example acceptance check: open a PR to main that renames a customer-visible settings label. The run should identify that PR, cite its diff, locate the affected Help Center article, suggest the precise label change with the article ID and leave the article unpublished pending review. A PR with only internal test changes should report no customer-facing update.

See Start a flow from GitHub events, Automation for Docs and Publish documents to the help center.