GitHub repo launch checklist and audit. Use when user says "launch", "go public", "publish repo", "audit repo for launch", "open source this", "make public", "launch checklist", or wants to prepare a private repo for public release. Also works for auditing already-public repos. Covers: secret scanning, README polish, SEO metadata, license, templates, visibility change, distribution, and post-launch verification.

8-phase workflow for launching a repo (private->public) or auditing an existing public repo. Hard gate on secrets (Phase 1 blocks everything). Soft checks on everything else.

Phase 0: Repo State Detection

# Visibility + basic stats
gh repo view --json visibility,stargazerCount,forkCount,description,repositoryTopics,url

If visibility: PUBLIC: skip Phase 6 (Go Public), run all other audits
If visibility: PRIVATE: full workflow including Phase 6
Note the owner/repo for all subsequent commands

Phase 1: Security Audit (HARD GATE)

If ANY secrets found: STOP. List them. Do not proceed to Phase 2.

Source code scan

# Common secret patterns
grep -rn --include="*.{js,ts,py,sh,md,json,yml,yaml,toml,env}" \
  -E "(AIza|sk_|ghp_|gho_|vcp_|sbp_|glpat-|xox[bps]-|AKIA|shpat_|phc_|re_[A-Za-z0-9])" . \
  | grep -v node_modules | grep -v .git | head -30

# Passwords and tokens in config
grep -rn --include="*.{js,ts,py,sh,json,yml,yaml,toml,env}" \
  -iE "(password|passwd|secret|token|api_key|apikey|private_key)\s*[:=]" . \
  | grep -v node_modules | grep -v .git | grep -v ".example" | head -20

# Private IPs, emails, phone numbers
grep -rn -E "(10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2[0-9]|3[01])\.\d+\.\d+)" . \
  | grep -v node_modules | grep -v .git | head -10

Git history scan (last 50 commits)

git log -50 --all -p | grep -iE "password|api_key|secret|token|private_key" | head -20

Gitleaks (if available)

command -v gitleaks &>/dev/null && gitleaks detect --source . --no-banner

.gitignore coverage

Verify .gitignore includes: .env*, *.pem, *.key, credentials*, node_modules/, .DS_Store, *.sqlite, *.db

If missing entries, add them before proceeding.

HARD GATE: If secrets found, list each one with file:line and stop. User must remediate.

Phase 2: Repository Hygiene

# Repo size and file count
du -sh --exclude=.git . 2>/dev/null || du -sh .
find . -not -path './.git/*' -not -path './node_modules/*' | wc -l

# Bloat check: large files
find . -not -path './.git/*' -not -path './node_modules/*' -size +1M -exec ls -lh {} \;

# TODO/FIXME with internal context
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.js" --include="*.ts" --include="*.py" \
  --include="*.sh" --include="*.md" . | grep -v node_modules | head -20

# Files that shouldn't be public
find . -not -path './.git/*' -iname "*draft*" -o -iname "*internal*" -o -iname "*personal*" \
  -o -iname "*workplan*" -o -iname "*notes*" 2>/dev/null | head -10

.env.example completeness

# Find all env var references in code
grep -rn --include="*.{js,ts,jsx,tsx}" "process\.env\." . | grep -v node_modules | \
  sed 's/.*process\.env\.\([A-Z_]*\).*/\1/' | sort -u

# Compare against .env.example
test -f .env.example && cat .env.example | grep -v "^#" | grep "=" | cut -d= -f1 | sort -u

Report any env vars referenced in code but missing from .env.example.

Phase 3: Documentation Audit

Read references/readme-checklist.md for the full README quality checklist.

Quick checks

# README exists and has content
test -f README.md && wc -l README.md

# LICENSE exists
test -f LICENSE && head -5 LICENSE

# Broken links in README
grep -oP 'https?://[^\)\" >]+' README.md 2>/dev/null | while read url; do
  status=$(curl -sL -o /dev/null -w "%{http_code}" --max-time 5 "$url" 2>/dev/null)
  [ "$status" != "200" ] && echo "BROKEN ($status): $url"
done

# Broken image references
grep -oP '!\[.*?\]\((.*?)\)' README.md 2>/dev/null | grep -oP '\((.+?)\)' | tr -d '()' | while read img; do
  [[ "$img" == http* ]] && continue
  [ ! -f "$img" ] && echo "MISSING IMAGE: $img"
done

Templates

# Issue templates
ls .github/ISSUE_TEMPLATE/ 2>/dev/null || echo "No issue templates"

# Contributing guide
test -f CONTRIBUTING.md && echo "CONTRIBUTING.md exists" || echo "No CONTRIBUTING.md"

Suggest creating issue templates (bug report + feature request) if missing.

Phase 4: GitHub SEO & Metadata

Landscape check

# See what competing repos use for description and topics
gh search repos "<relevant keywords>" --limit 5 --json name,description,repositoryTopics

Set metadata

# Description (< 160 chars, keyword-rich)
gh repo edit --description "<description>"

# Homepage URL (if applicable)
gh repo edit --homepage "<url>"

# Topics (5-10, steal relevant ones from top repos)
gh repo edit --add-topic "<topic1>" --add-topic "<topic2>"

Topic strategy:

Include: tool/framework name, primary language, domain keywords
Add "open-source" as a topic
Look at what top 5 competing repos use

# Check if custom OG image is set
gh api repos/{owner}/{repo} --jq '.open_graph_image_url // "No custom image"'

If no custom image: recommend creating a 1280x640 social preview. Upload via GitHub Settings > Social preview.

Phase 5: CI & Install Verification

# Check for CI
ls .github/workflows/ 2>/dev/null || echo "No CI workflows"

# If package.json exists: test install
test -f package.json && (cd /tmp && rm -rf test-launch && git clone "$(gh repo view --json url -q .url)" test-launch && cd test-launch && npm install && echo "Install OK" || echo "Install FAILED")

# If requirements.txt: test install
test -f requirements.txt && pip install -r requirements.txt --dry-run 2>&1 | tail -5

# If install script exists: test it
test -f install.sh && (cd /tmp && rm -rf test-launch && git clone "$(gh repo view --json url -q .url)" test-launch && cd test-launch && bash install.sh && echo "Install OK" || echo "Install FAILED")

# Dependency audit
test -f package.json && npm audit 2>/dev/null | tail -10

Phase 6: Go Public (skip if already public)

Final secret scan (repeat Phase 1 one last time)

Run the same secret scan commands from Phase 1. If anything new appeared, STOP.

Make public

gh repo edit --visibility public

Enable features

# Enable Discussions (optional, suggest for community projects)
gh api repos/{owner}/{repo} -X PATCH -f has_discussions=true

Create release

gh release create v1.0.0 --title "v1.0.0" --notes "$(cat <<'EOF'
## What's included
- [List key features from README]

## Quick start

[Install command from README]


## Requirements
[List from README]
EOF
)"

Phase 7: Distribution & Discovery

Identify concrete targets:

Awesome lists: search GitHub for awesome-<domain> repos. Open a PR to add the repo.
Communities: identify 2-3 where the target audience is:
- Reddit: r/programming, r/webdev, r/commandline, r/selfhosted, etc.
- Hacker News: Show HN post
- Discord servers for the framework/language
- LinkedIn (if B2B/professional audience)
Cross-reference: if part of an org (e.g., BuildingOpen), add to other repos' "Related Projects" sections.

Draft announcement copy: what it does (1 sentence), why it exists (1 sentence), link.

Phase 8: Post-Launch Verification

# Test clone from HTTPS
git clone "$(gh repo view --json url -q .url)" /tmp/test-clone && ls /tmp/test-clone && rm -rf /tmp/test-clone

# Verify metadata
gh repo view

# Check traffic (after 24-48h)
gh api repos/{owner}/{repo}/traffic/clones --jq '.clones[] | [.timestamp,.count] | @tsv'
gh api repos/{owner}/{repo}/traffic/views --jq '.views[] | [.timestamp,.count] | @tsv'

# Early engagement
gh issue list
gh api repos/{owner}/{repo} --jq '.stargazers_count'

Verify README renders correctly on GitHub (no broken images, formatting issues). Test social preview by sharing the URL and checking OG image renders.

Output Format

Present results as a checklist:

## Launch Audit: {repo-name}
Visibility: PUBLIC/PRIVATE | Stars: N | Forks: N

### Phase 1: Security [PASS/FAIL]
- [x] No secrets in source code
- [x] No secrets in git history
- [x] .gitignore covers sensitive files

### Phase 2: Hygiene [PASS/WARN]
- [x] No bloat files
- [ ] 3 TODOs found (non-blocking)

... (continue for all phases)

Rules

Phase 1 (Security) is a HARD GATE. If it fails, nothing else matters. Fix secrets first.
All other phases are soft: report issues, suggest fixes, but don't block.
For private->public: run Phase 6 only after Phases 1-5 pass.
For already-public repos: skip Phase 6, run everything else as an audit.
Never auto-publish or auto-make-public. Always confirm with user before gh repo edit --visibility public.
Clean up /tmp/test-* directories after install verification.

Skill metadata

Visibility: public
Type: Workflow
Version: v1.0.0
Source: cli
Verified: ✓