private-github-repo-upload
Safely initialize, sanitize, commit, create, and push a local project with private runtime data to a separate private GitHub repository. Use when the user asks to back up or upload a local data-bearing project to a private GitHub repo while keeping public Skills separate. Never uploads credentials, environments, caches, or public Skill source.
Private GitHub Repository Upload
Use this as a fixed, auditable workflow. It is a Workflow, not an autonomous discovery agent: project scope, exclusion policy, and repository name must be explicit or use a documented default confirmed by the user.
Workflow
Step 1: [Deterministic] Confirm scope
- Identify the exact local project directory.
- Identify the GitHub owner and repository name.
- Confirm the repository is private.
- Treat private strategy state, portfolio state, risk state, reports, and historical snapshots as uploadable only when the user explicitly approves a data-bearing private backup.
- Keep public Skill directories outside the private repository unless the user explicitly asks for a separate copy.
Step 2: [Deterministic] Inspect and define exclusions
- Verify the project directory exists and is not a broad personal directory.
- Read any existing
.gitignorebefore modifying it; create one when absent. - Whitelist variant (mixed workspace): when the project sits inside a workspace that also holds unrelated personal material (e.g. legal, health, or family documents that must never be tracked), ignore everything by default and negate only allowed paths. Three gotchas: start with
/*(not*); always include!/.gitignoreitself (easy to miss —git add .gitignorethen fails with "paths are ignored"); and for nested paths re-include each parent directory before its children (!/.workbuddy→.workbuddy/*→!/.workbuddy/build→.workbuddy/build/*→!/.workbuddy/build/*.py). The whitelist also protects future files dropped at the root from being tracked by accident. - Exclude local environments, bytecode, IDE state, temporary files, rebuildable output, machine-local WorkBuddy memory/automation state, backups, credential files, private keys, API keys, and
.envfiles. - Keep the exclusion list narrow enough that approved strategy and research data remain available.
Step 3: [Deterministic] Initialize and stage safely
- Initialize a local repository with the intended default branch, for example
git init -b main. - Stage only after the ignore rules are in place.
- Inspect the staged manifest, file count, and total size.
- Scan staged text for GitHub tokens, bearer tokens, private keys, API keys, passwords, webhook secrets, and unexpected absolute credential paths.
- Run
git diff --cached --check; existing whitespace warnings are reportable but are not a reason to alter historical material merely for upload.
Step 4: [Deterministic] Commit locally
- Set a local Git identity only if needed; do not change global identity.
- Create one descriptive initial commit.
- Stage paths explicitly, one
git addper logical group, and never pass a gitignored path.git add -A <path> <gitignored-path>exits non-zero, so in an&&chain thegit commitnever runs. - Verify with
git log -1that the commit actually exists before pushing. Do not assume a chainedgit commitsucceeded. A commit that silently did not happen leaves HEAD at the previous SHA, and Step 6B will then faithfully replicate that stale HEAD as a spurious empty commit on the remote (identical tree and message, different SHA,files: []). - Verify the commit SHA and that the working tree is clean.
- Do not push until the local commit and staged manifest pass inspection.
Step 5: [Deterministic] Create or reuse the private remote
- Read the configured GitHub PAT from the approved secure credential source or environment variable without printing it.
- Authenticate with the GitHub REST API and verify the authenticated account.
- Look up the target repository before creating it.
- If lookup returns 404, create it with
private: true. - If creation returns 422 because the name already exists, retry by listing the authenticated owner’s repositories and verify the exact repository, privacy, and owner before continuing.
- On a network/API failure, retry once or twice and cross-check with an independent client before reporting an environment failure.
Step 6: [Deterministic] Push without persisting credentials
- Add or set a credential-free
originURL. - Push with a non-persistent credential mechanism such as
GIT_ASKPASSor an approved credential helper; do not put the PAT in a remote URL, command argument, shell history, script, or repository. - Push the intended branch only. Do not force-push.
- If
git pushhangs with no output (reproduced repeatedly on Windows/Git Bash behind a proxy): abort it and fall back to Step 6B. Do not keep retrying the same hanging command, and do not report it as a network failure without trying the API path.
Step 6B: [Deterministic] Manual push via the Git Data API
Use git/blobs → git/trees → git/commits → PATCH git/refs/heads/<branch> to advance the remote. Four constraints are mandatory; violating any of them produces a silently divergent history rather than an error:
base_treemust be the REMOTE commit's tree. A local tree oid does not exist on the remote and returns422 base_tree is not a valid tree oid.- Pass the local commit's full
author/committermetadata, with the local UTC offset preserved. GitHub writes the date as+0000when omitted. If the local commit is+0800, the commit objects differ byte-for-byte and the remote SHA diverges from the local one — the histories look equivalent (identical tree) but fork permanently. Convert git raw1788157141 +0800to local wall-clock ISO2026-08-31T14:19:01+08:00. - Extract the message with
git cat-file commit HEADand take everything after the first blank line.git log -1 --format=%Bplus.trim()drops the trailing newline and changes the SHA. - Read changed files with
git -c core.quotePath=false diff-tree .... Without it, CJK paths are escaped to"reports/601985_\345\255\243..."andfs.existsSyncfails on every one of them.
After creating the commit, assert remote_commit.sha === local_head_sha before advancing the ref. If they differ, do not push — fix the metadata first.
If a divergent commit was already pushed, do not force-reset or force-push to rewrite the remote — Hard Rule 5 forbids it regardless of who created the commit. Recover without rewriting history: rebuild the intended tree from API metadata and advance the branch with a new forward commit (a git revert of the bad change, or a corrected commit through the normal PATCH-ref path with force: false). If the remote tip is not the one you expect, or the commit may be shared, stop and report the divergence for explicit user approval — never assume nobody else is based on it. Any exception requires explicit approval, preserving the current remote tip and an atomic expected-SHA check that aborts if the remote changed.
Step 7: [Deterministic] Verify remote state
- Read the remote branch SHA and compare it with the local commit SHA. Get the remote SHA from the API (
GET /repos/{owner}/{repo}/branches/main), notgit ls-remote: a private repo makes ls-remote require authentication too, and without the same askpass/credential setup used for the push it silently waits on a username/password prompt and hangs (auto-backgrounding, no error). The push itself having succeeded does not make a later bare ls-remote safe. - Verify the repository is private, the owner and repository name are correct, and the default branch is correct.
- Verify the local working tree is clean and the configured
originURL contains no credential. - Report the exact uploaded scope and exclusions.
- For gitignored private files (risk-state.json, portfolio-state.json, etc.), verify the CONTENT actually reached the remote — a
files: []on the created commit is a known false signal, not proof of an empty push. Do not trustgit hash-objectfor this: Git normalizes line endings (CRLF/LF) before hashing the working-tree file, so the localgit hash-objectSHA almost always differs from the remote blob SHA even when the bytes are identical. Instead verify one of two ways:- Raw-byte blob SHA: compute
sha1("blob " + byteLength + "\0" + rawFileBytes)in Node/Python on the local file, and compare it to theshaof that path's entry in the remotegit/trees/<sha>?recursive=1. If they match, the file is byte-identical on the remote. - Contents API decode:
GET /repos/{owner}/{repo}/contents/<path>?ref=<remote-sha>, base64-decodecontent, and compare to the local file bytes (or grep for a known unique substring). This is the most reliable end-to-end check.
- Do NOT conclude a gitignored file is "missing/lost" from a
git hash-objectmismatch alone. Confirm with method 1 or 2 before re-pushing.
- Raw-byte blob SHA: compute
Hard Rules
- Public Skills and private runtime data remain separate repositories.
- Never commit or print GitHub, Notion, webhook, cloud, database, or other credentials.
- Never upload a home directory, Desktop, Downloads, Documents, or broad personal directory as a project.
- Never use
git addbefore the exclusion policy is established and inspected. - Never use force-push, destructive reset, or remote deletion in this workflow.
- Private repository status must be verified through the authenticated API; a successful push alone is not proof of privacy.
- A 404/422 or network error must not be treated as a final diagnosis after one request; retry and cross-check first.
- If the staged scan finds a real secret, stop the upload, remove it from the index and history before any push, and rotate the exposed credential when applicable.
Pitfalls
- A private repository may return 404 from a direct repository lookup while still appearing in the authenticated owner repository list; treat a 422 name conflict as an identity/visibility lookup problem and cross-check the owner list.
- A credential embedded in a push URL can leak through process arguments, logs, or copied commands even when the remote URL is later reset; use an ephemeral credential channel instead.
git diff --cached --checkmay report historical trailing whitespace; do not rewrite old reports solely to make the initial backup cosmetically clean.- A script that imports a public Skill from a sibling directory will not be portable after cloning; report the dependency rather than copying public Skill source into the private repository.
git pushcan hang indefinitely rather than failing, and the harness may auto-background and then kill it. A hang is not a permission or network verdict; switch to the Git Data API instead of reporting an environment failure.- A remote commit created through the API can carry an identical tree but a different SHA than the local commit when dates or the message trailing newline differ. Identical trees prove content equality; only a matching commit SHA proves history alignment. Always check the SHA.
git diff-tree --name-onlyappliescore.quotePathescaping to non-ASCII paths. This fails silently on Windows with CJK filenames — the file simply appears deleted and gets skipped, producing a commit that is missing files without any error.PATCH /git/refs/heads/<branch>rejects non-fast-forward updates with422 Update is not a fast forward. Undoing a bad commit needsforce: true, which is exactly the operation Hard Rule 5 forbids, so the correct remedy is to avoid creating the bad commit by validating metadata first.- A chained
git commitcan silently not happen, and the push script will then create a spurious empty commit.git add -A <good-path> <gitignored-path>exits non-zero ("The following paths are ignored by one of your .gitignore files"), which short-circuits the&&chain, sogit commitnever runs. The push helper still readsHEAD, finds the previous commit, and replicates it as a new remote commit with the same tree and message but a different SHA andfiles: []. Detect it by runninggit log -1before pushing and confirming the printed SHA matches the new commit; recover withROLLBACK=<previous-sha>and then commit and push properly. Never chain "add && commit && push" without verifying the commit landed. git hash-objectlies about gitignored private-file sync because of CRLF normalization. Git applies the repo's line-ending policy (e.g.core.autocrlf/.gitattributes) when hashing the working-tree file, sogit hash-object <file>yields a different SHA than the raw bytes actually stored in the remote blob — even when local and remote are byte-identical. Symptom:git hash-objectshows localce50…≠ remote tree070b…, but the file is in fact synced. Verify with the raw-byte blob SHA (Nodecrypto:sha1("blob "+len+"\0"+bytes)) or a contents-API decode instead. Never treat agit hash-objectmismatch as evidence that a private file failed to upload.
Failure Handling
| Scenario | Action |
|---|---|
| Project path is missing or too broad | Stop and request an exact project path |
| User did not approve private data upload | Stage code and non-sensitive research material only; keep runtime state local |
| Secret pattern or credential file is staged | Stop; fix ignore rules and unstage it; do not push |
| Repository lookup is 404 | Create the repository as private, then verify it |
| Creation is 422 name-already-exists | List the authenticated owner repositories and reuse only the exact private target |
| API call fails once | Retry and cross-check with another client before assigning blame to network or permissions |
| Push fails | Keep the local commit; inspect URL, branch, token scope, and remote state; never force-push as a shortcut |
| Push hangs with no output | Abort and switch to Step 6B (Git Data API); a hang is not evidence of a network or permission problem |
| API commit SHA differs from local HEAD | Do not advance the ref. Check the UTC offset in author/committer dates and the trailing newline in the message, then recreate |
| Ref update returns 422 not-a-fast-forward | Never force over unknown history. If the bad commit is your own and unshared, use the documented ROLLBACK path; otherwise stop and report |
| Remote SHA differs | Stop and report; do not overwrite remote history automatically |
Output Format
Return a concise completion record containing:
- Local project path
- Remote repository URL
- Privacy and default-branch verification
- Local and remote commit SHA comparison
- Uploaded top-level scopes and sensitive/runtime exclusions
- Whether the local working tree is clean
- Any unresolved portability issue, such as a dependency on a public Skill outside the repository
- Downloads
- Security audit
- Pass
- Last updated
- 17h ago
- Current version
- v1.1.1
- License
- MIT-0
