Github Repo Sync

GitHub Repo Sync

Use this skill when the user wants to upload a local project to GitHub, bind a local repo to a GitHub remote, or keep a repo in sync with GitHub.

This skill is especially useful on this machine because GitHub HTTPS may reset mid-connection, while SSH authentication is available and can be routed through port 443 when needed.

Core Workflow

1. Inspect local repo state first.
   • Check whether the target folder is already a git repo.
   • Check branch, remotes, working tree status, and git user identity before changing anything.
2. Prepare local history.
   • If the folder is not yet a repo, initialize git.
   • Make sure there is at least one local commit before the first push.
   • For shareable repos, remove obvious caches, outputs, cookies, tokens, and local-only runtime state before committing.
3. Connect the GitHub remote safely.
   • Add or update origin rather than creating duplicate remotes.
   • Use scripts/set-github-remote.ps1 when you want a deterministic helper for this step.
4. Prefer the safest transport that works.
   • HTTPS is acceptable when stable.
   • If GitHub HTTPS fails with connection resets on this machine, switch to SSH.
   • If port 22 is blocked or unreliable, use GitHub SSH over port 443.
   • Use scripts/ensure-github-ssh-443.ps1 to append the github.com -> ssh.github.com:443 host rule when needed.
5. Fetch before pushing.
   • Always inspect the remote branch before the first push to a repo you did not create in this session.
   • If the remote contains a GitHub-created initial commit such as LICENSE or .gitignore, fetch and merge it instead of force-pushing over it.
   • If local and remote histories are unrelated, prefer git merge origin/main --allow-unrelated-histories --no-edit after inspecting the remote content.
6. Push and verify.
   • Push with upstream tracking: git push -u origin <branch>.
   • Confirm the push succeeded and that the local branch tracks the remote branch.

Safety Rules

• Never force-push unless the user explicitly asks for it.
• Never overwrite or discard remote initialization commits without inspecting them first.
• Never push secrets, cookies, tokens, .env files, browser session state, or obvious machine-local caches unless the user explicitly wants that.
• If a repo is dirty with unrelated user changes, work with them or stop and confirm, rather than sweeping them away.
• If GitHub authentication is missing, stop and tell the user exactly which auth step is blocking progress.

Machine Notes

• gh may be unavailable on this machine. Do not depend on GitHub CLI unless you verify it exists first.
• GitHub HTTPS may fail with Recv failure: Connection was reset. Treat that as a transport problem, not necessarily a bad repo URL.
• SSH authentication is available locally and can be validated with:

ssh -T git@github.com

• If needed, GitHub SSH over 443 can be validated with:

ssh -T -p 443 git@ssh.github.com

Helpers

This skill includes two low-risk local helpers:

• scripts/ensure-github-ssh-443.ps1 Ensures ~/.ssh/config contains a Host github.com block that routes through ssh.github.com on port 443.
• scripts/set-github-remote.ps1 Initializes a repo if needed, then safely adds or updates a remote such as origin.

Use these helpers for setup steps, then continue with normal git commands for fetch, merge, commit, and push.

Common Flows

Publish a local folder to a new GitHub repo

1. Inspect local status.
2. Initialize git if needed.
3. Add .gitignore / README / share-safe structure if appropriate.
4. Commit locally.
5. Set origin.
6. Fetch remote.
7. Merge any remote initialization commit if present.
8. Push main.

Sync an existing local repo to GitHub

1. Check status and remotes.
2. Fetch origin.
3. Review divergence before merging or pushing.
4. Push only after confirming local changes are ready.

Publish a skill pack

When the repository is meant to share Codex skills:

• Prefer skills/<skill-name>/... layout.
• Include a concise repo-level README.md.
• Add install commands that use Codex's skill-installer.
• Keep runtime caches such as node_modules, tmp/, output/, and browser session state out of git.

References

Read references/common-flows.md for reusable command sequences and error-handling patterns.