github-sync-helper

name	github-sync-helper
description	General GitHub basic operations + GitHub platform objects (Issues/Labels/Milestones/Releases/Actions) automation skill (Minis environment). Triggers when user mentions "GitHub how to, clone, init, remote, branch, commit, push, pull, fetch, merge, rebase, tag, release, issues, actions, labels, milestone, protect branch, fork, PR, sync to upstream, delete branch, clear then restore directory, push main, one-click sync" or any Git/GitHub basic operations and workflows.
compatibility	Requires git, python3. Uses env GITHUB_TOKEN for GitHub API + HTTPS push (non-interactive via GIT_ASKPASS).

Goal

Solidify GitHub/Git "basic operations" and common collaboration workflows into:

1. Clear command reference (explanation + when to use)
2. Executable one-click scripts (avoid repetitive manual steps)
3. Numbered output for easy selection replies (e.g., repo list)

Safety & Constraints (Must Follow)

#	Rule	Reason
1	Do not output Token: No command should echo/print $GITHUB_TOKEN to stdout	Prevent leaks
2	Confirm dangerous operations: Delete branch, clear directory, force overwrite, force push, push main	Poor reversibility
3	Default to "branch + PR" workflow; only "push main" when user explicitly requests	Reduce damage to main branch
4	Run git status before push/pull	Prevent mistaken commits/overwrites

How to Run

• Script entry: sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh <command> [options]

Script runs in the "current git repo directory" (must be inside a repo).

Git/GitHub Basic Operations Reference (Explanation + Script Mapping)

#	Category	Operation	One-line Description	Common Command	Script Support
1	Init	init	Turn current directory into a git repo	git init	init
2	Clone	clone	Download repo from remote to local	git clone <url>	clone
3	Remote	remote	Manage origin/upstream remotes	git remote -v/add/set-url/remove	remotes/add-remote/add-upstream/set-remote-url/remove-remote
4	Branch	branch	View/create/delete branches	git branch -a/-d/-D	branches/create-branch/delete-branches
5	Switch	checkout/switch	Switch to a branch	git switch <b>	checkout
6	View Changes	status/diff/log	View workspace changes/diffs/history	git status git diff git log	status/diff/log
7	Stage	add	Add changes to staging area	git add -A	add
8	Commit	commit	Package staging into a commit	git commit -m "..."	commit
9	Sync	fetch/pull/push	Fetch/merge/push commits	git fetch git pull git push	fetch/pull/push/push-main
10	Merge	merge/rebase	Merge branch history	git merge git rebase	merge/rebase (use with caution)
11	Stash	stash	Temporarily save uncommitted changes	git stash	stash
12	Tag	tag	Tag a commit with version	git tag	tag
13	Submodule	submodule	Manage sub-repo dependencies	git submodule	submodule
15	GitHub Platform	issues/labels/milestones/releases/actions	Manage platform objects via GitHub API	(API)	gh-issues-list etc. (see below)

Note: The script aims to "turn common basic operations into reusable commands". For complex rebase/conflicts, interactive terminal is still recommended.

GitHub Platform Operations (API)

Requirement: needs env GITHUB_TOKEN.

#	command	Description
1	`gh-issues-list --repo <owner/repo> [--state open	closed
2	gh-issue-create --repo <owner/repo> --title <t> [--body <b>]	Create Issue
3	gh-issue-close --repo <owner/repo> --number <n>	Close Issue
4	gh-labels-list --repo <owner/repo>	List labels
5	gh-label-create --repo <owner/repo> --name <n> [--color <rrggbb>] [--description <d>]	Create label
6	`gh-milestones-list --repo <owner/repo> [--state open	closed
7	gh-milestone-create --repo <owner/repo> --title <t> [--description <d>] [--due <YYYY-MM-DD>]	Create milestone
8	gh-releases-list --repo <owner/repo>	List releases
9	`gh-release-create --repo <owner/repo> --tag <vX.Y.Z> --name [--body ] [--draft true	false] [--prerelease true
10	gh-actions-list --repo <owner/repo>	List workflows
11	gh-actions-dispatch --repo <owner/repo> --workflow <id_or_file> [--ref <branch>] [--inputs <json>]	Trigger workflow_dispatch manually

Script Command Reference (gh_sync.sh)

#	command	Description
2	clone --url <url> [--dir <path>]	Clone repo to specified directory
3	remotes	Show current remotes
4	add-remote --name <n> --url <url>	Add remote
5	set-remote-url --name <n> --url <url>	Change remote URL
6	remove-remote --name <n>	Delete remote
7	add-upstream --upstream <owner/repo>	Add upstream remote
8	status	git status --porcelain + brief hints
9	diff [--staged]	View diff
10	log [--n <k>]	View recent commits
11	branches	List local and remote branches
12	create-branch --name <b> [--from <ref>]	Create branch
13	checkout --name <b>	Switch branch
14	delete-branches --keep <branch>	Delete local/remote branches except keep
15	add --path <p>	git add
16	commit --message <m>	git commit
17	fetch [--remote <n>]	Fetch remote updates
18	pull [--remote <n>] [--branch <b>]	Pull and merge
19	push [--remote <n>] [--branch <b>]	Push
20	push-main	Push current main to origin (non-interactive with token)
21	empty-dir --dir <path>	Empty a directory in repo but keep it (with .gitkeep)
22	restore-dir --src <path> --dst <path>	Overwrite-restore from local directory to repo directory (deletes dst contents first)
23	pr --upstream <owner/repo> --head <owner:branch> --base <branch> --title <t> --body <b>	Create PR via GitHub API
24	gh-issues-list ... etc.	GitHub platform object operations (issues/labels/milestones/releases/actions)

Typical Workflows (Examples)

1) Push main: empty dir -> restore dir -> push

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh empty-dir --dir self-improving-agent
sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh restore-dir --src /var/minis/skills/self-improving-agent --dst self-improving-agent
sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh commit --message "restore(self-improving-agent): sync from local"
sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh push-main

4) Replace repo target file contents only (keep original path/filename), then commit and push

Scenario: user requests "replace content only" "replace the worker inside" "keep original repo filename/path", meaning: only overwrite target file content, do not add source filename, do not change target path in repo.

Recommended execution order:

# 1. Fetch/refresh repo
repo_dir=/var/minis/workspace/<repo>
if [ -d "$repo_dir/.git" ]; then
  cd "$repo_dir" && git fetch --all --prune && git reset --hard origin/main
else
  gh repo clone <owner/repo> "$repo_dir"
fi

# 2. Content overwrite only: overwrite repo target file with source file content
cp <source_file> "$repo_dir/<target_path>"

# 3. If git identity not configured, prefer reuse GitHub login name with GitHub noreply email
cd "$repo_dir"
git config user.name '<GitHub display name>'
git config user.email '<login>@users.noreply.github.com'

# 4. Commit and push main (only when user explicitly requests commit/push)
git add <target_path>
git commit -m 'replace <target_path> content'
git push origin main

Execution notes:

• When user says "replace content only", understand as: keep original file path and filename in repo, only overwrite content.
• Do not put source filename directly into repo; target should still be the original file (e.g., worker.js).
• If target path is known, overwrite directly; if unknown, locate target file in repo first before replacing.
• If Author identity unknown error before commit, write in current repo:
  • git config user.name '<GitHub display name>'
  • git config user.email '<login>@users.noreply.github.com'
• Default to git fetch + git reset --hard origin/main first to avoid mistaken commits on stale working tree.
• If user has explicitly requested "commit"/"push", proceed directly without reconfirmation.

5) Delete all branches except main (local + remote)

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh delete-branches --keep main

6) Without creating branch, fork:main -> upstream:main open PR directly

sh /var/minis/skills/github-sync-helper/scripts/gh_sync.sh pr \
  --upstream OpenMinis/MinisSkills \
  --head mowenyun:main \
  --base main \
  --title "sync: ..." \
  --body "..."

• Repo list output must use Markdown table, include # column for user to select by number.
• Suggested fields: # | Repo (owner/repo) | Visibility | Fork | Default Branch | Last Updated | URL
• Interaction hint: "Reply with number to continue (clone/pull/commit-push/content-replace etc.)".

Note: If user needs more fields (description, language, stars), add --json ... extension.

#	Issue	Handling
1	push fails could not read Username	Needs env GITHUB_TOKEN, script uses GIT_ASKPASS for non-interactive auth
2	API 401/403	Token insufficient permissions (repo/public_repo) or expired
3	not inside a git repo	cd to repo directory first (or use clone/init)