| name | github-sync-upstream |
| description | Sync code from an upstream GitHub repository into a target fork (e.g., opendatahub-io midstream). Detects remotes from the current repo, or clones fresh if run from outside. Fetches upstream, merges into a sync branch, restores protected files, resolves conflicts, and opens a PR to the target GitHub repo. Use when asked to sync upstream, merge upstream changes, or bring a GitHub fork up to date with its upstream source. |
| allowed-tools | Bash Read AskUserQuestion |
| user-invocable | true |
| argument-hint | [commit-sha] |
| compatibility | Requires git. gh CLI (authenticated) needed only for PR creation. |
| metadata | {"author":"zdtsw","version":"1.0","tags":"github, sync, upstream, fork, merge"} |
Sync Upstream
Merge upstream commits into a sync branch on the user's fork and open a
PR to the target repo. See references/workflow.md for exact script
invocations, exit-code handling, and the summary template.
Commit SHA (optional): $ARGUMENTS
Step 1: Determine Working Context
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || REPO_ROOT=""
If REPO_ROOT is non-empty, run scripts/detect-remotes.sh --repo "${REPO_ROOT}"
and ask via AskUserQuestion whether this is the correct repo.
If yes → Step 2A. If no or not in a repo → Step 2B.
Step 2A: In-Repo Setup
Pre-fill upstream/target from detect-remotes output. Ask via
AskUserQuestion to confirm: upstream repo, target repo, branches
(default main). Run scripts/setup-remotes.sh, parse UPSTREAM_REMOTE and
TARGET_REMOTE. Save ORIGINAL_BRANCH from current HEAD.
Step 2B: Clone From Scratch
Ask for upstream repo, target repo, and branches. If the user has a
local clone, use its path and continue as Step 2A. If not, ask if they
have a GitHub fork — run scripts/clone-fork.sh then scripts/setup-remotes.sh. If
no fork exists, ask them to create one and re-run. Stop.
Save ORIGINAL_BRANCH from current HEAD.
Step 3: Protected Files
Protected files keep the target version, discarding upstream changes.
Ask via AskUserQuestion for glob patterns to protect (or none).
Suggest common examples: OWNERS*, .tekton/*.yaml,
Dockerfile*konflux.
Step 4: Pre-flight Check
Verify origin does not point to upstream or target. If it does, tell
the user to set origin to their personal fork and stop.
Step 5: Merge
Run scripts/sync-merge.sh. Handle exit codes 0 (success), 1 (conflicts), and
3 (duplicate branch) as described in references/workflow.md.
Step 6: Push and Open PR
Show PR summary and ask via AskUserQuestion: open a PR or just push?
If confirmed, run scripts/open-pr.sh.
Step 7: Cleanup and Summary
Check out ORIGINAL_BRANCH. For Path B clones, inform the user of the
temp directory. Display the summary per references/workflow.md.
