fix(ci): prevent duplicate PRs in publish-docs workflow

[etserend]

Summary

• Use a static branch name (feat/update-docs-${GITHUB_REF_NAME}) instead of a run_id-suffixed one, so re-runs update the same branch
• Force-push to update the existing branch on each run
• Check for an existing open PR before calling gh pr create, and skip creation if one already exists

This applies the same pattern fixed in PR #139 (regenerate-api-client.yaml) to the publish-docs workflow.

Test plan

• Trigger the workflow twice from the same branch — second run should update the existing PR, not open a new one
• Verify the generated docs are correctly committed to the docs branch

🤖 Generated with Claude Code

[fercor-cisco]

🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.

Verdict: request_changes — The duplicate-PR check filters on --base main but gh pr create omits -B main, so if the docs repo's default branch isn't main the dedup silently breaks; and dropping the no-changes guard now opens/churns a PR on every run even with zero doc changes.

Follow-ups

Suggested follow-up work that could be tracked as Shortcut stories:

• .github/workflows/publish-docs.yaml:53-53: The git fetch origin ... 2>/dev/null suppresses stderr, which hides genuine fetch failures (auth/network) and makes the fallback to git checkout -b indistinguishable from the expected 'branch does not exist yet' case. Consider checking for the ref explicitly (e.g. git ls-remote --exit-code --heads origin <branch>) so real errors aren't masked.

[fercor-cisco]

🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.

Verdict: request_changes — Branch-reuse step likely fails to check out the existing docs branch and force-push then discards reviewer commits; empty-commit noise concern remains unaddressed.

Follow-ups

Suggested follow-up work that could be tracked as Shortcut stories:

• .github/workflows/publish-docs.yaml:98-99: Shell variables like $BRANCH_NAME are used unquoted in gh pr list --head $BRANCH_NAME and gh pr create ... -H $BRANCH_NAME. It works today because branch names contain no whitespace, but quoting ("$BRANCH_NAME") would silence shellcheck SC2086 and is more defensive. Non-blocking style cleanup.

[fercor-cisco]

🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.

Verdict: approve — Small, well-scoped CI fix; all four prior review findings are resolved in the current HEAD and the logic matches the proven regenerate-api-client pattern.

Follow-ups

Suggested follow-up work that could be tracked as Shortcut stories:

• .github/workflows/publish-docs.yaml:53-53: The git fetch ... && git checkout -B ... FETCH_HEAD || git checkout -b ... uses the A && B || C idiom: if git checkout -B ... FETCH_HEAD were to fail after a successful fetch, the || fallback would silently create a fresh branch off the docs repo's default branch, and the later git push --force could clobber the existing remote branch (including reviewer commits). Low probability, but an explicit if git fetch ...; then git checkout -B ... FETCH_HEAD; else git checkout -b ...; fi would remove the ambiguity.