Skip to content

ci(docs): open documentation PRs when public API changes #202

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
markbackman merged 1 commit into from
Aug 28, 2026
Merged

ci(docs): open documentation PRs when public API changes #202

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
360 changes: 360 additions & 0 deletions .github/workflows/update-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,360 @@
# Opens a documentation PR against pipecat-ai/docs when a change to this
# package's public API merges. The skill it follows is shared, published from
# pipecat-ai/pipecat through the pipecat-dev-skills marketplace; the mapping it
# applies is this repo's own .claude/skills/update-docs/SOURCE_DOC_MAPPING.md.
#
# Requires two repository secrets that do not exist here yet:
# DOCS_BOT_APP_ID, DOCS_BOT_PRIVATE_KEY — the same GitHub App pipecat uses.
# This repo is in daily-co while the docs repo is in pipecat-ai, so the App
# token is minted for owner pipecat-ai and scoped to `docs` alone. Reading this
# repo's own PRs uses the default GITHUB_TOKEN, which needs no extra grant.
#
# Until those secrets are set, the workflow will fail at its first step rather
# than run and do nothing.

name: Update Documentation on PR Merge

on:
pull_request_target:
types: [closed]
branches: [main]
# Everything shipped in the package is in scope, named as exclusions so a new
# directory is covered the day it appears rather than when someone remembers
# to list it.
paths:
- "src/pipecatcloud/**"
- "!src/pipecatcloud/tests/**"
workflow_dispatch:
inputs:
pr_number:
description: "PR number to generate docs for"
required: true
type: string

jobs:
update-docs:
if: >-
github.event_name == 'workflow_dispatch' ||
github.event.pull_request.merged == true
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
contents: read
# write so a run that fails can say so on the PR that triggered it;
# issues: write covers the label, which goes through the issues API
pull-requests: write
issues: write
id-token: write
steps:
- name: Generate app token
id: app-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ secrets.DOCS_BOT_APP_ID }}
private-key: ${{ secrets.DOCS_BOT_PRIVATE_KEY }}
owner: pipecat-ai
repositories: |
docs

- name: Checkout pipecat-cloud
uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Checkout docs
uses: actions/checkout@v4
with:
repository: pipecat-ai/docs
token: ${{ steps.app-token.outputs.token }}
path: _docs

- name: Record docs baseline
id: docs-base
working-directory: _docs
# The commit the docs branch builds on, used to scope formatting to the
# pages this run touches.
run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"

- name: Resolve PR number
id: pr
run: |
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
echo "number=${{ inputs.pr_number }}" >> "$GITHUB_OUTPUT"
else
echo "number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
fi

- name: Determine assignee
id: assignee
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
run: |
PR_AUTHOR=$(gh pr view ${{ steps.pr.outputs.number }} \
--repo daily-co/pipecat-cloud --json author --jq '.author.login')

# Assign the PR author only if they're a maintainer (== member of the
# pipecat-ai org). Org members all have at least read access to the docs
# repo, so they're assignable there; the assignees probe guards against
# future access changes. Otherwise leave the PR unassigned for triage.
ASSIGNEE=""
if gh api "orgs/pipecat-ai/members/$PR_AUTHOR" --silent 2>/dev/null \
&& gh api "repos/pipecat-ai/docs/assignees/$PR_AUTHOR" --silent 2>/dev/null; then
ASSIGNEE="$PR_AUTHOR"
fi

echo "login=$ASSIGNEE" >> "$GITHUB_OUTPUT"
if [ -n "$ASSIGNEE" ]; then
echo "Docs PR will be assigned to: $ASSIGNEE"
else
echo "PR author is not an org member; docs PR will be left unassigned."
fi

- name: Update documentation
uses: anthropics/claude-code-action@v1
env:
DOCS_TOKEN: ${{ steps.app-token.outputs.token }}
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
github_token: ${{ secrets.GITHUB_TOKEN }}
prompt: |
You are updating documentation for the pipecat-ai/docs repository based on
changes merged in PR #${{ steps.pr.outputs.number }} of daily-co/pipecat-cloud.

## Setup

1. Read the shared skill instructions at `.claude/skills/update-docs/SKILL.md`
2. Read this repo's profile at `.claude/skills/update-docs/SOURCE_DOC_MAPPING.md`
3. The docs repository is checked out at `./_docs/`

## Get the diff

Run `gh pr diff ${{ steps.pr.outputs.number }}` to see what changed in the PR.
Also run `gh pr diff ${{ steps.pr.outputs.number }} --name-only` to get the list of changed files.
Filter to source files matching the profile's Scope section (SKILL.md Step 3).

If no relevant source files were changed, exit with "No documentation changes needed."

## Follow the skill instructions

Apply the SKILL.md workflow (Steps 3-10) with these adaptations for automation:

### Docs path
Use `./_docs/` — it's already checked out. Do not ask for a path.

### Branch management
- Branch name: `docs/cloud-pr-${{ steps.pr.outputs.number }}`
- Work inside `./_docs/` for all doc edits and git operations
- Check if the branch already exists on the remote:
```bash
cd _docs && git fetch origin docs/cloud-pr-${{ steps.pr.outputs.number }} 2>/dev/null
```
- If it exists: check it out (supports workflow re-runs)
- If not: create it from main

### Git config
Before committing in `_docs`, set:
```bash
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
```

### No interactive questions
Do not ask questions. If you encounter gaps (unmapped files, missing sections,
ambiguous changes), note them in the PR body under "## Gaps identified".

### Creating the docs PR
After committing all changes in `_docs`, push and create a PR:
```bash
cd _docs
git push -u origin docs/cloud-pr-${{ steps.pr.outputs.number }}
GH_TOKEN=$DOCS_TOKEN gh pr create \
--repo pipecat-ai/docs \
--label auto-docs \
--label pipecat \
--title "docs: update for pipecat PR #${{ steps.pr.outputs.number }}" \
--body "$(cat <<'BODY'
Automated documentation update for [pipecat-cloud PR #${{ steps.pr.outputs.number }}](https://github.com/daily-co/pipecat-cloud/pull/${{ steps.pr.outputs.number }}).

## Changes
<summarize each doc page updated and what changed>

## Gaps identified
<any unmapped files, missing doc pages, or missing sections — or "None">
BODY
)"
```

### Re-run handling
If `gh pr create` fails because a PR from that branch already exists,
push the updated commits and use `gh pr edit` to update the body instead.

### Recording the outcome
Every run must leave a one-line verdict at
`$RUNNER_TEMP/docs-update-outcome.txt`, written before you finish:

- `PR: <url>` — a docs PR was created or updated
- `NOOP: <reason>` — no docs change was needed, naming the specific
reason (e.g. "only internal wiring in pipeline/task_manager.py changed;
no public API affected")

A bare "no changes needed" is not a reason. This file is how a reader
later tells a deliberate no-op from a run that quietly fell short, so
write it even when the answer seems obvious.

### No-op
If after analyzing the diff you determine no documentation changes are needed
(e.g., only skip-listed files changed, or changes don't affect public API docs),
write the `NOOP:` line described above and exit cleanly without creating a
branch or PR.

A file being a base class or a shared module is NOT by itself a reason to
skip it. Public constructor parameters, event handlers, and behavior belong
in the docs wherever they live — see the mapping file's Skip list for the
short set of genuinely internal files.

### Formatting and llms.txt
Skip SKILL.md Step 9. A later workflow step runs Prettier over the pages
this branch touches and regenerates `llms.txt` / `llms-full.txt`, so leave
both to it rather than running them yourself.

## Important rules
- Only modify files inside `./_docs/` — never modify pipecat source code
- Follow the conservative editing rules from SKILL.md Step 6
- Read each doc page fully before editing (SKILL.md Guidelines)
- Use `GH_TOKEN=$DOCS_TOKEN` for all `gh` commands targeting pipecat-ai/docs
claude_args: |
--model claude-sonnet-4-5-20250929
--max-turns 90
--allowedTools "Read,Write,Edit,Glob,Grep,Bash"

# Pinned from the docs repo's own .nvmrc rather than left to whatever the
# runner image ships, so formatting and generated files match what
# contributors produce.
- name: Set up Node
if: always()
uses: actions/setup-node@v4
with:
node-version-file: _docs/.nvmrc

- name: Format docs and regenerate llms.txt
if: always()
working-directory: _docs
run: |
BRANCH="docs/cloud-pr-${{ steps.pr.outputs.number }}"
if [ "$(git rev-parse --abbrev-ref HEAD)" != "$BRANCH" ]; then
echo "No docs branch checked out; nothing to do."
exit 0
fi

# Format only the pages this branch touches, so the docs PR diff stays
# limited to the changes under review.
CHANGED=$(mktemp)
git diff --name-only --diff-filter=d -z \
"${{ steps.docs-base.outputs.sha }}" HEAD > "$CHANGED"
if [ ! -s "$CHANGED" ]; then
echo "No doc changes to format."
exit 0
fi

# The docs repo pins Prettier, so this matches what its pre-commit hook
# produces. `--ignore-unknown` skips files Prettier has no parser for.
npm ci --no-audit --no-fund
xargs -0 npx prettier --ignore-unknown --write < "$CHANGED"

# The docs repo checks in llms.txt and llms-full.txt, and its metadata
# lint fails when either is stale. llms-full.txt embeds page bodies
# verbatim, so generation runs after Prettier has settled them.
node scripts/gen-llms-txt.mjs

if git diff --quiet; then
echo "Doc changes are already formatted and llms.txt is current."
exit 0
fi

git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
git commit -am "chore: format docs and regenerate llms.txt"
git push origin "$BRANCH"

- name: Assign docs PR
if: always()
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
run: |
ASSIGNEE="${{ steps.assignee.outputs.login }}"
if [ -z "$ASSIGNEE" ]; then
echo "No assignee resolved; leaving docs PR unassigned."
exit 0
fi
PR_URL=$(gh pr list --repo pipecat-ai/docs \
--head docs/cloud-pr-${{ steps.pr.outputs.number }} \
--state open --json url --jq '.[0].url')
if [ -z "$PR_URL" ]; then
echo "No open docs PR for branch docs/cloud-pr-${{ steps.pr.outputs.number }}; nothing to assign."
exit 0
fi
gh pr edit "$PR_URL" --add-assignee "$ASSIGNEE"
echo "Assigned $PR_URL to $ASSIGNEE"

# The run summary states the outcome either way, so a run that documented
# nothing is distinguishable from one that produced a docs PR.
- name: Record outcome
if: always()
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
run: |
PR_NUMBER="${{ steps.pr.outputs.number }}"
DOCS_PR=$(gh pr list --repo pipecat-ai/docs \
--head "docs/cloud-pr-$PR_NUMBER" --state all \
--json url --jq '.[0].url' 2>/dev/null || true)

{
echo "## Docs automation for pipecat-cloud PR #$PR_NUMBER"
echo
if [ -n "$DOCS_PR" ]; then
echo "Docs PR: $DOCS_PR"
elif [ -f "$RUNNER_TEMP/docs-update-outcome.txt" ]; then
echo "No docs PR. Reported outcome:"
echo
echo '```'
cat "$RUNNER_TEMP/docs-update-outcome.txt"
echo '```'
else
echo "No docs PR and no recorded outcome — the run did not reach the"
echo "point of stating one. Treat this PR as undocumented."
fi
} >> "$GITHUB_STEP_SUMMARY"

# Nothing outside the Actions tab surfaces a failed run, so it is reported
# on the PR that triggered it.
- name: Report failure on the source PR
if: failure() && steps.pr.outputs.number != ''
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PR_NUMBER: ${{ steps.pr.outputs.number }}
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
run: |
gh label create docs-automation-failed \
--repo daily-co/pipecat-cloud \
--color B60205 \
--description "The update-docs workflow failed for this PR" \
2>/dev/null || true

gh pr edit "$PR_NUMBER" --repo daily-co/pipecat-cloud \
--add-label docs-automation-failed 2>/dev/null || true

gh pr comment "$PR_NUMBER" --repo daily-co/pipecat-cloud --body "$(cat <<BODY
**Docs automation failed for this PR — its documentation is missing.**

The \`update-docs\` workflow did not produce a docs PR: [run log]($RUN_URL)

Re-run it once the cause is addressed:

\`\`\`
gh workflow run update-docs.yml -f pr_number=$PR_NUMBER --repo daily-co/pipecat-cloud
\`\`\`

If this PR genuinely needs no documentation, remove the
\`docs-automation-failed\` label.
BODY
)"
Loading