Local App GitHub Publishing

Local App GitHub Publishing

Use this when the user asks to push a local app/prototype/project to GitHub for the first time, especially Electron, iOS/Xcode, mobile, desktop, or AI/API-integrated apps.

This skill complements the protected github-repo-management skill with the user-specific first-push hygiene: publish the useful source, not the machine's junk drawer wearing a trench coat.

Core Rule

Before the first commit, sanitize and verify. Generated builds, dependency folders, local Xcode state, and API credentials do not belong in the initial history.

Default Behavior

• Default visibility: private unless the user explicitly asks for public.
• Use a simple repo name matching the user's wording when possible, normalized to GitHub style, e.g. “iOS translator” → ios-translator.
• If the repo name exists, choose the closest available variant only if the user gave broad wording; otherwise ask.
• Set a repo-local git identity if global user.name / user.email are missing.
• Verify the pushed remote before reporting success.

First-Push Workflow

1. Confirm project and GitHub auth

cd /path/to/project
git --version
gh auth status
GH_USER=$(gh api user --jq .login)
gh api user --jq .id

2. Check whether the target repo exists

gh repo view "$GH_USER/REPO" --json nameWithOwner,url,visibility 2>&1 || true

3. Create or tighten .gitignore before git add

Include at least:

# Dependencies
node_modules/
.venv/
.venv-*/

# Build outputs
dist/
dist-*/
release/
release-*/
*.tsbuildinfo

# Local caches/logs
.npm-cache/
.npm-logs/
*.log

# Xcode / Apple local state
.DerivedData/
DerivedData/
*.xcuserstate
xcuserdata/
.DS_Store

# Environment / secrets
.env
.env.*
!.env.example
*.pem
*.p8
*.p12
*.mobileprovision

4. Run a source-only secret scan

Exclude generated/dependency directories. Search for common key patterns:

• AIza — Google/Gemini keys
• sk- — OpenAI-style keys
• ghp_, github_pat_ — GitHub tokens
• hf_ — Hugging Face tokens
• -----BEGIN ... PRIVATE KEY-----

If a real secret is found, stop and remove/rotate before committing.

5. Initialize git and stage

git init -b main 2>/dev/null || git init
git add -A
git status --short

6. Verify staged content before committing

git diff --cached --name-only | wc -l
git check-ignore -v node_modules release dist-renderer dist-electron .DerivedData .DS_Store 2>/dev/null || true
python3 - <<'PY'
import os, subprocess
files = subprocess.check_output(['git','diff','--cached','--name-only'], text=True).splitlines()
found = False
for f in files:
if os.path.exists(f) and os.path.getsize(f) > 20*1024*1024:
print(f, os.path.getsize(f))
found = True
if not found:
print('No staged files over 20MB')
PY

7. Set repo-local identity if needed

GH_USER=$(gh api user --jq .login)
GH_ID=$(gh api user --jq .id)
git config user.name "$GH_USER"
git config user.email "${GH_ID}+${GH_USER}@users.noreply.github.com"

8. Commit and push

git commit -m "Initial app commit"
gh repo create REPO --private --source . --remote origin --push --description "Short description"

9. Verify remote

git status --short --branch
git ls-remote origin refs/heads/main
gh repo view "$GH_USER/REPO" --json nameWithOwner,url,visibility,defaultBranchRef,pushedAt

Publishing a Long-Running Local Branch for the First Time

Use this before the first remote push of a substantial campaign, repair, or autoresearch branch in an existing repository—not only before a repository’s initial push.

1. Verify the complete branch range, not just the working tree:

• git diff --check main...HEAD catches whitespace already committed.
• Scan git log -p --format= main..HEAD for credential patterns; scanning only current files misses secrets added and later removed.
• Inventory local filesystem paths, machine-local emails, and personal identifiers separately from actual credentials. Private branches may intentionally retain diagnostic paths, but public publication requires sanitizing them.

2. Inspect author and committer metadata across main..HEAD. If an unpushed branch contains automatic workstation identities, normalize it before first push:

• create a local backup ref;
• record HEAD^{tree} and git rev-list --count main..HEAD;
• rewrite only the unpushed branch to the established noreply identity;
• require the final tree hash and commit count to remain identical;
• rerun the full gate afterward. Never rewrite already-shared history without explicit authorization.

3. Confirm the remote branch does not already exist with git ls-remote --heads before deciding whether a normal push or coordinated force-with-lease workflow applies.
4. Push the named branch only, then verify local HEAD equals git ls-remote for that exact ref and that the working tree tracks the intended remote branch.
5. Update any campaign state/report that records final SHAs after metadata normalization or push. Record branch push separately from PR, merge, tag, release, and deployment; do not imply one from another.

Merging a Completed Branch into Protected Main

When the user asks to merge a named feature branch:

1. Resolve the branch's actual repository before acting. If it is absent from the current repository, search session history for the exact branch name instead of concluding it does not exist.
2. Fetch/prune, compare origin/main...origin/<branch>, and inspect the complete commit range.
3. On the feature branch, run both git diff --check origin/main...HEAD and git diff --check; the former catches committed whitespace defects while the latter validates any unstaged cleanup.
4. Run the repository's canonical tests and an independent security/privacy review for substantive public changes. Normalize public commit identity to the established GitHub noreply address.
5. Open a PR, wait for all required checks, then merge—prefer squash when cleanup-only commits should not survive as separate history.
6. Pull main --ff-only, verify the PR merge state and live default-branch files, and wait for post-merge main CI. PR checks and post-merge checks are separate gates.
7. Treat local branch deletion as optional housekeeping. If an approval gate denies it, stop and report that only the local branch remains; do not retry or misreport the merge as incomplete.

Public README Readiness

Before making a repository public, make the README understandable to someone who has no session context:

1. The first paragraph must explain in plain language what the project does, what input/action it takes, how success is determined, and what happens to the result. Prefer concrete verbs over labels such as “provider-agnostic harness” or “iterative framework.”
2. State consequential boundaries early—for example, whether changes are committed locally, reverted, uploaded, pushed, or published automatically.
3. For a non-trivial loop or architecture, place one explanatory diagram near the top. Prefer an accessible SVG with a native viewBox, embedded by relative path and supplied with useful Markdown alt text.
4. Verify the diagram in a real browser at its native aspect ratio; square thumbnail generators can crop wide SVGs and produce a false visual failure.
5. After merge, inspect the rendered GitHub repository page, not only the source Markdown. Confirm the image resolves with expected dimensions and alt text. If raw.githubusercontent.com briefly serves stale content, verify the default-branch SHA and use GitHub's Contents API with ?ref=main or the exact commit SHA before concluding the merge failed.

README SVG quality gate

For a hand-authored architecture/flow SVG:

1. Validate the XML before visual review: xmllint --noout docs/diagram.svg.
2. Render at the SVG's native aspect ratio. On macOS, prefer sips -s format png docs/diagram.svg --out /tmp/diagram.png; qlmanage -t creates square thumbnails and can crop or mis-scale a wide diagram, producing misleading QA evidence.
3. Use portable SVG text styling (font-family, font-size, font-weight) rather than a complex font: shorthand. Include Arial/Helvetica/sans-serif fallbacks so GitHub and native rasterizers agree more closely.
4. Inspect the raster for clipped labels, card overflow, connector lines crossing unrelated cards, ambiguous arrow direction, and readable contrast at README width.
5. Embed responsively, for example <img src="docs/diagram.svg" alt="..." width="100%">; avoid forcing a fixed 1200-pixel width inside GitHub's narrower content column.
6. Have an independent reviewer compare every diagram claim against the current implementation and check the changed diff for secrets/PII before publication. Resolve accuracy and rendering findings before commit.