██████╗ ██╗████████╗██╗  ██╗██╗   ██╗██████╗
██╔════╝ ██║╚══██╔══╝██║  ██║██║   ██║██╔══██╗
██║  ███╗██║   ██║   ███████║██║   ██║██████╔╝
██║   ██║██║   ██║   ██╔══██║██║   ██║██╔══██╗
╚██████╔╝██║   ██║   ██║  ██║╚██████╔╝██████╔╝
 ╚═════╝ ╚═╝   ╚═╝   ╚═╝  ╚═╝ ╚═════╝ ╚═════╝

   your machine (Git)                         GitHub (remote)
 ┌────────────────────┐    git push     ┌────────────────────┐
 │ working dir        │ ─────────────▶  │  origin/master     │
 │   └ staging (index)│                 │  PRs · Actions ·    │
 │       └ .git/ (commits, branches)    │  Issues · Security  │
 └────────────────────┘ ◀───────────── └────────────────────┘
                          git pull

# Install Git + the GitHub CLI
winget install Git.Git GitHub.cli     # Windows
brew install git gh                    # macOS
sudo apt install git gh               # Debian/Ubuntu (incl. WSL)

# One-time identity
git config --global user.name  "Your Name"
git config --global user.email "you@codeamani.com"
git config --global init.defaultBranch main
git config --global pull.rebase false   # merge on pull (or 'true' to rebase)

# Authenticate the CLI (browser flow; stores a token securely)
gh auth login

git init                      # start a repo here   (or: gh repo clone owner/name)
git status                    # what changed?
git add file.ts               # stage a change      (git add -A for everything)
git commit -m "feat: add login form"
git log --oneline --graph     # see history as a graph
git diff                      # unstaged changes    (git diff --staged for staged)

git switch -c feature/mpesa-stk      # create + switch (old: git checkout -b)
git switch master                    # switch back
git branch                           # list local branches
git branch -d feature/mpesa-stk      # delete a merged branch

gh repo create codeAmani/my-app --private --source=. --push   # create + link + push
# …or link an existing remote
git remote add origin https://github.com/codeAmani/my-app.git
git push -u origin master            # -u sets the upstream once
git pull                             # fetch + merge remote changes
git fetch origin                     # download without merging

# .gitignore — never track secrets or build junk
.env*
node_modules/
.next/
*.log

git merge feature/x                  # merge feature/x into current branch
git rebase master                    # replay current branch on top of master
git rebase -i HEAD~3                  # interactively squash/reorder last 3 commits
# Golden rule: never rebase commits you've already pushed to a shared branch.

merge:   A───B───C (master)          rebase:  A───B───C───D'──E' (master)
              \                                (D,E replayed cleanly on top)
               D───E (feature) ──▶ merge commit M

gh pr create --title "feat: M-Pesa STK push" --body "Implements Daraja STK flow"
gh pr create --fill                  # use branch name + last commit as title/body
gh pr list                           # open PRs
gh pr view 42 --web                  # open in browser
gh pr checks 42                      # CI status for the PR
gh pr merge 42 --squash --delete-branch

gh pr diff 42                        # read the changes
gh pr review 42 --approve
gh pr review 42 --request-changes --body "Validate the phone format (2547…)"
gh pr review 42 --comment --body "Nice — one nit inline"

git switch feature/x
git merge master                     # conflict markers appear in files
# Edit the <<<<<<< / ======= / >>>>>>> sections, choosing the right code, then:
git add resolved-file.ts
git commit                           # completes the merge

gh issue create --title "Bug: STK callback times out" --label bug,priority:high
gh issue list --assignee @me
gh issue close 17 --comment "Fixed in #42"
# Projects (v2) — track work on a board; manage via the GraphQL API or the UI
gh project list --owner codeAmani

gh api -X PUT repos/codeAmani/my-app/branches/master/protection \
  -F required_pull_request_reviews.required_approving_review_count=1 \
  -F required_status_checks.strict=true \
  -F enforce_admins=true

# .github/workflows/ci.yml
name: CI
on:
  push: { branches: [master] }
  pull_request: { branches: [master] }
  workflow_dispatch:           # manual "Run workflow" button

permissions:
  contents: read               # least privilege by default

concurrency:                   # cancel superseded runs on the same ref
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [20, 22]         # run across versions in parallel
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v4
        with: { node-version: ${{ matrix.node }}, cache: npm }
      - run: npm ci
      - run: npm test

  deploy:
    needs: test                # only after test passes
    if: github.ref == 'refs/heads/master'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: echo "Deploy step (Vercel auto-deploys on push for codeAmani)"

gh workflow list
gh workflow run ci.yml --field environment=production
gh run watch                   # live-stream the active run
gh run view 12345678 --log

# Releases (auto-generate notes from merged PRs)
gh release create v1.2.0 --generate-notes
gh release list
# Packages — publish to GitHub Packages (npm/Container/etc.)
# npm: set "publishConfig": { "registry": "https://npm.pkg.github.com" } then `npm publish`

# .github/dependabot.yml — keep npm deps current weekly
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule: { interval: "weekly" }

# .github/workflows/codeql.yml — CodeQL code scanning
name: CodeQL
on: { push: { branches: [master] }, pull_request: { branches: [master] } }
jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions: { security-events: write, contents: read }
    steps:
      - uses: actions/checkout@v5
      - uses: github/codeql-action/init@v3
        with: { languages: javascript-typescript }
      - uses: github/codeql-action/analyze@v3

// .devcontainer/devcontainer.json
{
  "image": "mcr.microsoft.com/devcontainers/javascript-node:22",
  "features": { "ghcr.io/devcontainers/features/github-cli:1": {} },
  "postCreateCommand": "npm install",
  "customizations": { "vscode": { "extensions": ["dbaeumer.vscode-eslint"] } }
}

gh codespace create -r codeAmani/my-app
gh codespace code            # open in VS Code

# publishes ./dist to Pages
permissions: { pages: write, id-token: write }
# … build, then:
- uses: actions/upload-pages-artifact@v3
  with: { path: dist }
- uses: actions/deploy-pages@v4

# REST — anything the API exposes
gh api repos/codeAmani/my-app/pulls --jq '.[].title'
gh api -X POST repos/codeAmani/my-app/issues -f title="From the CLI" -f body="…"
# GraphQL — precise, fewer round-trips
gh api graphql -f query='query { viewer { login } }'
# Aliases + JSON output power scripting
gh pr list --json number,title,author --jq '.[] | "\(.number) \(.title)"'

export GITHUB_TOKEN=github_pat_...   # gh + MCP read this (GH_TOKEN also works)
# Generate at: https://github.com/settings/tokens

claude mcp add -s user --transport http github \
  https://api.githubcopilot.com/mcp \
  -H "Authorization: Bearer ${GITHUB_TOKEN}"

// .mcp.json
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

claude mcp add github -- docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  -e GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" \
  ghcr.io/github/github-mcp-server

<!-- .claude/commands/review-pr.md -->
Review pull request #$ARGUMENTS.
1. Use the GitHub MCP to fetch the PR diff + description and existing comments.
2. Analyse for bugs, security issues, missing tests, and convention drift.
3. Post a review: approve if safe, else request changes with specific line notes.

// scripts/auto-pr.js — open a PR after a feature branch is pushed (Stop hook)
import { execFileSync } from "child_process";       // execFileSync = no shell injection
const branch = execFileSync("git", ["branch", "--show-current"]).toString().trim();
if (branch === "main" || branch === "master") process.exit(0);
if (execFileSync("git", ["status", "--porcelain"]).toString()) process.exit(0);
try { execFileSync("gh", ["pr", "create", "--fill"], { stdio: "inherit" }); } catch {}

# .github/workflows/ai-fix.yml — headless Claude fixes lint on new PRs
name: AI Auto-fix
on: { pull_request: { types: [opened] } }
jobs:
  fix:
    runs-on: ubuntu-latest
    permissions: { contents: write, pull-requests: write }
    steps:
      - uses: actions/checkout@v5
        with: { ref: ${{ github.head_ref }} }
      - uses: actions/setup-node@v4
        with: { node-version: '22' }
      - run: npm install -g @anthropic-ai/claude-code
      - env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: claude -p "Fix all ESLint errors" --allowedTools "Bash,Edit,Read,Glob,Grep" --output-format text
      - run: |
          git config user.name "Claude Code Bot"; git config user.email "noreply@github.com"
          git add -A && git diff --staged --quiet || git commit -m "fix: auto-fix ESLint errors"
          git push

# Daily loop
git status / git add -A / git commit -m "…" / git push
git switch -c feature/x      # branch        git switch master
git pull --rebase            # update cleanly  git stash / git stash pop
# History
git log --oneline --graph --all
git revert <sha>             # safe undo of a pushed commit
git reflog                   # find lost commits
# GitHub via gh
gh pr create --fill / gh pr checks 42 / gh pr merge 42 --squash --delete-branch
gh issue create / gh run watch / gh release create vX --generate-notes
gh api repos/OWNER/REPO/... # raw REST/GraphQL