floomhq 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:
- 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.