Reframing GitHub: Your External Brain and Build Factory
In the past, Git was just a progress-save tool for you, like game save points. You only used add, commit, and push.
But as a builder shipping cross-platform products with Swift/Rust/Python and heavy AI usage, GitHub is your virtual cloud office. Here:
AI Agent Workstation
As you have seen in PR review, GitHub is the standardized interface where advanced AI like Codex can inspect your project. Without PRs, AI cannot run full-scope static review.
Fully Automated Pipeline
After you push code to cloud, automation can run Rust tests, build Swift IPA artifacts, and even distribute directly to TestFlight.
Core Concepts and Engineering Standards
1. Branch — Your Parallel Universe
Do not edit directly on main. Use semantic branch prefixes so both your future self and AI reviewers can instantly understand intent.
git checkout -b feat/audio-engine # feat: build a new feature
git checkout -b fix/grdb-crash # fix: resolve a specific bug
git checkout -b refactor/ui-components # refactor: improve structure without behavior change
2. Commit — A Precise Story Checkpoint
Commit messages are prompts for AI reviewers. If you write "update", review focus is weak. If you write "fix: handle nil audio stream to prevent crash", AI targets null-safety issues.
git diff before committing to avoid shipping debug leftovers like print("test") or temporary hard-coded keys.
3. Pull Request (PR) — AI Quality Gate
Even if you work solo, always open a PR. A PR is the merge proposal from your feature branch to main, and it is the review contract for AI and automation.
Solo + AI Golden Workflow
For every feature or bug fix, follow this six-step loop. It maximizes AI leverage and prevents low-level mistakes.
Create a New Branch (Local)
git checkout main
git pull
git checkout -b feat/new-spider
Build Fast (with local AI tools like Cursor)
Generate and test code locally. This consumes your local compute and daily usage budget.
git add .
git commit -m "feat: init spider engine"
Push to Remote
git push -u origin feat/new-spider
Open PR and attach an architecture summary
When creating a PR, include the AI-generated fix summary. Example: “This PR fixes swallowed I/O errors in AudioFeatureExtractor.swift and wraps AVAudioPCMBuffer in a Sendable container.”
AI Deep Review (Code Review)
AI bots annotate concrete lines automatically. Important: if AI detects logic risks (for example silent failures), fix locally and push again; GitHub marks old comments outdated and keeps merge quality high.
Merge and Clean Up
After approval, click “Merge pull request”, then clean local branches:
git checkout main
git pull
git branch -d feat/new-spider # remove completed local branch
Multi-Language Stack and Large Files (LFS)
If you work across Swift, Rust, Python, and R, one rule is absolute: never commit build artifacts, only source code.
Primary Guardrail: .gitignore
Swift / macOS
- .DS_Store
- build/
- *.xcworkspace
- xcuserdata/
Rust
- target/
- **/*.rs.bk
- # Cargo.lock should be committed to lock dependencies
Pitfall Guide: Git LFS (Large File Storage)
As an AI/macOS developer, you will hit huge files such as .mlmodel, large audio samples, or pre-rendered videos. Direct push is rejected once a file exceeds 100MB.
Use Git LFS. It stores large binaries in object storage and keeps lightweight pointers in Git history.
git lfs track "*.mlmodel"
git lfs track "*.mp4"
git add .gitattributes
# after this, commit these files like normal
GitHub Actions: Your Free Cloud Linux Runner
For Python jobs, R data pipelines, and Rust backends, GitHub Actions is a practical automation backbone. On push or PR events, it runs your workflow on cloud runners.
Example: run Rust tests automatically with .github/workflows/rust-test.yml:
name: Rust CI
on:
pull_request: # trigger when PR is opened/updated
branches: [ "main" ]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run Tests
run: cargo test --verbose
⚠️ Note: GitHub Actions can run on macOS, but Apple certificates and provisioning setup are costly to maintain. For iOS/macOS packaging, prefer Xcode Cloud.
Xcode Cloud: End-to-End Apple CI/CD
For solo developers, manually selecting certificates, archiving, exporting IPA, and uploading through Transporter is repetitive and fragile.
Xcode Cloud is Apple’s official CI/CD platform, deeply integrated with GitHub and App Store Connect. The key advantage is near-zero maintenance for certs and provisioning profiles.
How to wire it into your GitHub workflow
No YAML needed; setup is fully graphical:
- Open Product > Xcode Cloud > Create Workflow in Xcode.
- Select the product target you want to package (for example, Sonodex_Multiplatform).
- Critical step: authorize GitHub access. Xcode opens the browser and requests repo authorization so Xcode Cloud can listen to push/PR events.
- Finish setup. With your Apple ID signed in, cert material is synchronized from App Store Connect.
Full Pipeline with AI
Combining the workflow from section 3 with Xcode Cloud gives you an almost fully automated software factory:
mainmain*In Xcode Cloud you can use environment scripts such as ci_pre_xcodebuild.sh to preinstall the Rust toolchain: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
Sonodex Case: From Warnings to Automation
Resolving “Ghost Conflicts” (.xcuserstate)
Issue: merging PR reported conflicts on UserInterfaceState.xcuserstate, and even blocked checkout main.
Fix: this file is local Xcode UI state and should never be tracked.
rm "Sonodex_MacOS.xcodeproj/project.xcworkspace/xcuserdata/kircerta.xcuserdatad/UserInterfaceState.xcuserstate"
# 2. Remove from Git index and commit
git rm --cached [file-path]
git commit -m "chore: stop tracking xcode user state"
Permission Block and Dependency Fix (HTTPS over SSH)
Issue: initial setup stalled because Xcode Cloud requested org-level GitHub permission related to groue (GRDB).
Fix and impact: the project was pulling dependencies via SSH. Switching to public HTTPS (https://github.com/groue/GRDB.swift.git) resolved it instantly and avoids CI auth traps.
Main Branch Protection and Targeted Fixes (Branching)
Action: faced with many Swift 6 strict-concurrency warnings (for example Sendable issues around AVAudioPCMBuffer), we avoided touching stable main and created fix/swift6-concurrency immediately.
Benefit: main stays runnable and releasable while experimentation remains isolated.
Offload Compute to Cloud (CI/CD Power)
Action: after batch-fixing locally, push to GitHub and open PR to trigger Xcode Cloud workflows.
Benefit: full builds and compatibility checks run in parallel on Apple cloud runners, freeing your local Mac for the next task.
Solo Developer CLI Cheatsheet
Daily Essential Commands
| git status | Check changed files and staging state |
| git add . | Stage all current changes |
| git commit -m "msg" | Create a version checkpoint with clear intent |
| git push -u origin branch-name | Push to remote (use -u on first push of new branch) |
Recovery Commands
| git restore <file> | Discard file changes and restore from HEAD |
| git reset --soft HEAD~1 | Undo last commit but keep file changes staged |
| git reset --hard HEAD~1 | Undo last commit and remove code changes (destructive) |
When Branch Switching Is Blocked
| git stash | Temporarily stash messy local edits (including noisy Xcode state changes) and clean your workspace instantly. |
| git fetch -p | Prune local “ghost branches” that were already removed on remote. |
High-Leverage Tool: GitHub CLI (gh)
If browser-driven PR flow feels slow, install GitHub CLI with brew install gh. Then create PRs directly from terminal:
gh pr create --title "feat: audio engine" --body "@codex review"