# Github Repo Sync

> Publish or sync a local folder or repository to GitHub. Use when Codex needs to initialize git, prepare a repo for GitHub sharing, connect or update the `origin` remote, switch from unstable GitHub HTTPS to SSH over 443 on this machine, fetch and merge remote initialization commits safely, or push ongoing local changes without force-pushing user work.

- Skill: `whisperas/github-repo-sync` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add whisperas/github-repo-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/whisperas/github-repo-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: WhisperAS (https://skillmd.com/u/whisperas)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/whisperas/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:

```powershell
ssh -T git@github.com
```

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

```powershell
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.