gh-launch

name

gh-launch

description

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.

GitHub Repo Launch Checklist

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

Social preview

# 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:

1. Awesome lists: search GitHub for awesome-<domain> repos. Open a PR to add the repo.
2. 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)
3. 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.