fix(ci): check out the sync branch before transforming, and serialize runs

[evanorti]

Mirrors cosmos/example#16 and #17 in the reverse direction. The forward workflow had the same structural bug; it has been fixed and verified in CI, and this brings the two back into parity.

Problem

docs-sync-to-example.yml transforms the tutorials into cosmos-example/ while still on main, then switches to the open sync branch to commit:

git stash
git fetch origin "$BRANCH"
git checkout "$BRANCH"
git stash pop

Popping a stash taken against main onto a branch that already carries overlapping changes conflicts:

CONFLICT (content): Merge conflict in docs/02-quickstart.md
$ echo $?
1

run: blocks execute under bash -e, so exit 1 fails the step. This is conditional, not constant: it fires when the transform output touches lines the sync branch already changed, which is exactly what happens when that branch carries an earlier version of the same edit. This is the likely cause of the unexplained 2026-04-10 failure, which ran while cosmos/example#9 had been open since March 31. That run's logs have expired, so the attribution is inference, not proof.

Without the stash, git checkout aborts outright with "local changes would be overwritten," which is how the forward workflow was failing.

Fix

Select the target branch and check it out first, while the tree is still clean, then transform directly onto it. Nothing is stashed and nothing is merged, so there is no conflict to hit.

Three supporting changes:

• Replaces the separate change-detection step with a git diff --cached --quiet guard, so an already-current branch exits cleanly rather than creating an empty commit.
• Adds a concurrency group, so two overlapping runs cannot derive divergent commits from the same branch revision and race on push, where the loser is rejected non-fast-forward and its update silently lost.
• Adds workflow_dispatch, so a sync PR left stale by a failed run can be brought current without waiting for the next docs edit. The loop guard is unaffected: with no head_commit on a dispatch, contains() is false and the job runs.

Verification

Against real clones of both repos, using the stale cosmos/example#9 branch as the existing-PR case, with the transform output edited to overlap lines that branch already changed:

• Old sequence: CONFLICT (content): Merge conflict in docs/02-quickstart.md, exit 1
• New sequence: exit 0, stages the correct refresh of all five doc files
• New sequence run twice: reports no changes instead of committing again

The equivalent fix in cosmos/example has since run green in CI twice, once updating an open sync PR and once correctly reporting nothing to do.

Note on cosmos/example#9

That sync PR has been open since 2026-03-31 and its branch is five months stale. Once this merges, the next reverse sync will reuse and wholesale refresh it, turning it into a large diff (~225 insertions, ~50 deletions) rather than the small one a reviewer might expect. Closing it first is probably cleaner, so the next run opens a fresh PR.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cosmos-docs	🟡 Building	–	Aug 25, 2026, 4:39 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[greptile-apps]

Greptile Summary

This PR repairs the reverse documentation-sync workflow by selecting an existing sync branch before transformation and eliminating the conflict-prone stash application.

• Adds manual dispatch and workflow-level concurrency.
• Reuses or creates the target branch before generating documentation.
• Stages transformed documentation and exits cleanly when there is no diff.
• Updates an existing sync PR or creates a new one after pushing the generated commit.

Confidence Score: 5/5

The PR appears safe to merge, with no actionable blocking or non-blocking defects identified in the changed workflow.

The workflow now transforms directly on the intended branch, avoids stash conflicts, skips empty commits, and serializes updates while preserving the newest generated state.

Important Files Changed

Filename	Overview
.github/workflows/docs-sync-to-example.yml	Reorders branch selection ahead of transformation, serializes runs, supports manual recovery, and consolidates empty-diff and PR update handling without introducing an actionable defect.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Push or manual dispatch] --> B[Checkout source and example repositories]
  B --> C{Open docs-sync PR exists?}
  C -->|Yes| D[Checkout existing PR branch]
  C -->|No| E[Create new sync branch]
  D --> F[Transform tutorials into example docs]
  E --> F
  F --> G[Stage docs directory]
  G --> H{Staged changes?}
  H -->|No| I[Exit successfully]
  H -->|Yes| J[Commit and push]
  J --> K{Existing PR?}
  K -->|Yes| L[Comment that PR was refreshed]
  K -->|No| M[Open new docs-sync PR]

Loading

_{Reviews (1): Last reviewed commit: "fix(ci): check out the sync branch befor..." | Re-trigger Greptile}