init

Author: nlhogsten

.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install shellcheck
+        run: sudo apt-get update && sudo apt-get install -y shellcheck
+
+      - name: Run lint
+        run: tests/lint.sh

.gitignore

@@ -0,0 +1,6 @@
+# Local/private reference docs (keep folder, ignore contents)
+docs/local-only/*
+!docs/local-only/.gitkeep
+
+# Backward-compatible direct path ignore
+docs/ssh_multi_account_setup.md

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 - 2026-02-14
+
+- Initial release.
+- Added interactive `scripts/setup.sh` with dry-run default.
+- Added `scripts/update-remotes.sh` for owner-to-alias URL migration.
+- Added key helper scripts and backup script.
+- Added examples for owner mapping and git `includeIf`.
+- Added docs and lint workflow.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,161 @@
+# SSH Multi-Account Setup (macOS + GitHub)
+
+Safe, script-first tooling to manage multiple GitHub accounts on one machine with separate SSH keys, host aliases, and dry-run defaults.
+
+## Features
+
+- Audits and backs up existing `~/.ssh` state before changes.
+- Generates separate Ed25519 keys per account.
+- Adds keys to `ssh-agent` and macOS keychain.
+- Optionally uploads keys through `gh` after explicit confirmation.
+- Writes a managed block in `~/.ssh/config` with account aliases.
+- Validates aliases using `ssh -T git@<alias>`.
+- Updates existing repo remotes with a safe dry-run workflow.
+
+## Repository Layout
+
+- `scripts/setup.sh`: Main idempotent setup flow.
+- `scripts/update-remotes.sh`: Convert remotes to alias-based SSH URLs.
+- `scripts/backup-keys.sh`: Back up SSH files.
+- `scripts/generate-key.sh`: Standalone key creation helper.
+- `scripts/generate-gh-actions-key.sh`: Optional CI key helper.
+- `examples/owner-map.conf.example`: Owner-to-alias mapping example.
+- `examples/gitconfig-includeIf.example`: Git identity routing example.
+- `docs/audit-and-verify.md`: Manual audit and verification steps.
+- `tests/lint.sh`: Shell lint script.
+
+## Prerequisites
+
+- macOS with OpenSSH
+- Bash 4+
+- `git`
+- Optional: `gh` (GitHub CLI) for key upload
+- Optional: `shellcheck` for lint checks
+
+## Quick Start
+
+```bash
+chmod +x scripts/*.sh tests/lint.sh
+scripts/setup.sh --dry-run
+scripts/setup.sh --apply
+```
+
+Interactive defaults:
+
+- accounts: `personal,work`
+- key names: `id_ed25519_personal`, `id_ed25519_work`
+- aliases: `github-personal`, `github-work`
+
+Explicit example:
+
+```bash
+scripts/setup.sh --apply \
+  --accounts "personal,work" \
+  --email-personal "you@personal.email" \
+  --email-work "you@work.email"
+```
+
+Non-interactive example:
+
+```bash
+scripts/setup.sh --apply --yes \
+  --accounts "personal,work" \
+  --email-personal "you@personal.email" \
+  --email-work "you@work.email" \
+  --key-personal "id_ed25519_personal" \
+  --key-work "id_ed25519_work" \
+  --alias-personal "github-personal" \
+  --alias-work "github-work"
+```
+
+## Update Remotes
+
+Dry-run by default:
+
+```bash
+scripts/update-remotes.sh --root "$HOME/code" --map examples/owner-map.conf.example --dry-run
+```
+
+Apply changes (with confirmation):
+
+```bash
+scripts/update-remotes.sh --root "$HOME/code" --map ~/.ssh/owner-map.conf --apply
+```
+
+## Manual Commands (Reference)
+
+Audit:
+
+```bash
+ls -la ~/.ssh
+ls -1 ~/.ssh/*.pub 2>/dev/null || echo "no .pub files found"
+ssh-add -l || echo "no keys loaded"
+gh ssh-key list
+```
+
+Backup:
+
+```bash
+mkdir -p ~/ssh-backups
+cp -v ~/.ssh/id_* ~/ssh-backups/ 2>/dev/null || echo "copied any id_* keys"
+ls -la ~/ssh-backups
+```
+
+Generate keys:
+
+```bash
+ssh-keygen -t ed25519 -C "you@personal.email" -f ~/.ssh/id_ed25519_personal
+ssh-keygen -t ed25519 -C "you@work.email" -f ~/.ssh/id_ed25519_work
+```
+
+Add to agent/keychain:
+
+```bash
+eval "$(ssh-agent -s)"
+ssh-add --apple-use-keychain ~/.ssh/id_ed25519_personal
+ssh-add --apple-use-keychain ~/.ssh/id_ed25519_work
+ssh-add -l
+```
+
+Upload with `gh` (optional):
+
+```bash
+gh auth login
+gh ssh-key add ~/.ssh/id_ed25519_personal.pub --title "MacBook Personal $(date +%F)"
+gh auth login
+gh ssh-key add ~/.ssh/id_ed25519_work.pub --title "MacBook Work $(date +%F)"
+```
+
+Use aliases in remotes:
+
+```bash
+git remote set-url origin git@github-personal:your-personal-username/repo.git
+git remote set-url origin git@github-work:your-work-username/repo.git
+```
+
+Validate:
+
+```bash
+ssh -T git@github-personal
+ssh -T git@github-work
+ssh -vT git@github-personal 2>&1 | sed -n '1,200p'
+```
+
+## Safety Rules
+
+- Never delete keys silently.
+- Keep backups until all fetch/push checks are successful.
+- `update-remotes.sh` is dry-run by default and confirms before apply.
+- `setup.sh` prompts before risky operations unless `--yes` is used.
+
+## Verification Checklist
+
+- [ ] `ssh -T git@github-personal` authenticates to the personal username.
+- [ ] `ssh -T git@github-work` authenticates to the work username.
+- [ ] Critical repositories can fetch and push.
+- [ ] `gh ssh-key list` reflects intended keys.
+- [ ] Backups exist under `~/ssh-backups/<timestamp>`.
+
+## Caution About Old Keys
+
+Only remove old keys after successful verification across all repos. Prefer staged cleanup and revoke old keys in GitHub first.

docs/audit-and-verify.md

@@ -0,0 +1,48 @@
+# Audit and Verify
+
+## Local Audit
+
+```bash
+ls -la ~/.ssh
+ls -1 ~/.ssh/*.pub 2>/dev/null || echo "no .pub files found"
+ssh-add -l || echo "no keys loaded"
+```
+
+If GitHub CLI is installed and authenticated:
+
+```bash
+gh ssh-key list
+```
+
+## Backups
+
+```bash
+scripts/backup-keys.sh --dry-run
+scripts/backup-keys.sh --apply
+```
+
+## Verify Aliases
+
+```bash
+ssh -T git@github-personal
+ssh -T git@github-work
+```
+
+Expected pattern:
+
+- `Hi <username>! You've successfully authenticated, but GitHub does not provide shell access.`
+
+## Verify Repository Access
+
+For representative repositories:
+
+```bash
+git fetch
+git push --dry-run
+```
+
+## Only Then: Key Cleanup
+
+- Revoke old keys on GitHub.
+- Remove old local keys with explicit commands and prompts.
+- Keep backup snapshots until all workflows remain stable.

docs/local-only/.gitkeep

@@ -0,0 +1,17 @@
+# ~/.gitconfig
+
+[includeIf "gitdir:~/code/personal/"]
+  path = ~/.gitconfig-personal
+
+[includeIf "gitdir:~/code/work/"]
+  path = ~/.gitconfig-work
+
+# ~/.gitconfig-personal
+[user]
+  name = Your Name
+  email = you@personal.email
+
+# ~/.gitconfig-work
+[user]
+  name = Your Work Name
+  email = you@work.email

examples/gitconfig-includeIf.example

@@ -0,0 +1,3 @@
+# owner=alias
+your-personal-username=github-personal
+your-work-org=github-work

examples/owner-map.conf.example

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<USAGE
+Usage: $(basename "$0") [--dry-run] [--yes] [--dest DIR]
+
+Back up SSH key material from ~/.ssh to ~/ssh-backups/<timestamp> by default.
+USAGE
+}
+
+DRY_RUN=true
+ASSUME_YES=false
+DEST_BASE="$HOME/ssh-backups"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run) DRY_RUN=true ;;
+    --apply) DRY_RUN=false ;;
+    --yes|--non-interactive) ASSUME_YES=true ;;
+    --dest)
+      shift
+      DEST_BASE="${1:-}"
+      [[ -n "$DEST_BASE" ]] || { echo "Missing value for --dest" >&2; exit 1; }
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+TS=$(date +%Y%m%d-%H%M%S)
+DEST_DIR="$DEST_BASE/$TS"
+SOURCE_DIR="$HOME/.ssh"
+
+if [[ ! -d "$SOURCE_DIR" ]]; then
+  echo "No ~/.ssh directory found at $SOURCE_DIR"
+  exit 0
+fi
+
+FILES=()
+while IFS= read -r line; do
+  FILES+=("$line")
+done < <(find "$SOURCE_DIR" -maxdepth 1 -type f \( -name 'id_*' -o -name '*.pub' -o -name 'config' -o -name 'known_hosts*' \) | sort)
+
+if [[ ${#FILES[@]} -eq 0 ]]; then
+  echo "No matching SSH files found to back up."
+  exit 0
+fi
+
+echo "Backup destination: $DEST_DIR"
+echo "Files to backup:"
+printf '  %s\n' "${FILES[@]}"
+
+if [[ "$DRY_RUN" == true ]]; then
+  echo "[DRY RUN] No files copied."
+  exit 0
+fi
+
+if [[ "$ASSUME_YES" != true ]]; then
+  read -r -p "Proceed with backup? [y/N] " reply
+  [[ "$reply" =~ ^[Yy]$ ]] || { echo "Cancelled."; exit 1; }
+fi
+
+mkdir -p "$DEST_DIR"
+for f in "${FILES[@]}"; do
+  cp -p "$f" "$DEST_DIR/"
+done
+
+echo "Backup complete: $DEST_DIR"