GitHub 一键发布助手

把本地项目一键发布到 GitHub，覆盖开源准备到推送的完整流程。

使用场景

• "帮我把这个项目发到 GitHub"
• "发布到 github" / "上传到 GitHub"
• "建个 github 仓库" / "push 到 github"
• "开源这个项目"

工作流程

Step 0 — 前置检查

1. 确认当前目录是否已有 git 仓库（.git/）
2. 检查 GitHub CLI gh 是否可用且已登录（gh auth status）
   • 未登录则提示用户执行 gh auth login，或走 Windows Credential Manager 的 git push 交互认证
3. 询问用户 GitHub 用户名、仓库名、是否私有、是否需要 LICENSE、初始 tag

Step 1 — 安全检查（⚠️ 强制）

绝不允许提交的内容：

• .env / .env.*（除了 .env.example）
• *.pem / *.key / id_rsa* / *.p12
• secrets.json / credentials.json 等含密码/token 文件
• __pycache__/ / node_modules/ / vendor/ / .venv/ / dist/ / build/
• .workbuddy/memory/（用户记忆，本地私密）
• IDE 配置（.idea/、.vscode/）

操作：

1. 先跑 git status，看哪些文件会被提交
2. 若发现敏感文件，立即告警并要求用户确认
3. 确保 .gitignore 已包含上述规则；缺失就补齐

Step 2 — 补齐开源标配文件

根据项目类型按需生成（用户已有则不覆盖）：

Step 3 — Git 初始化与提交

# 若未初始化
git init -b main

# 设置用户信息（若未配置）
git config user.name  ""
git config user.email ""

# 检查 remote
git remote -v
# 若没有 origin，先通过 gh 创建远程仓库：
gh repo create  --public --source=. --remote=origin
# --public 或 --private 根据用户选择

# 添加全部
git add .
git status  # 让用户过目

# commit（清晰的 conventional commit message）
git commit -m "feat: initial release vX.Y.Z
<简要说明>"

# 打 tag（可选）
git tag -a vX.Y.Z -m "vX.Y.Z"

Step 4 — 推送

git push -u origin main
# 若有 tag
git push origin vX.Y.Z

• Windows 下 git push 会弹出 Credential Manager 窗口，用户登录一次即可
• 若 gh 已登录，可直接通过 gh repo create 完成远程建仓 + push，无需打开浏览器

Step 5 — 完成反馈

输出：

• 仓库 URL：https://github.com//
• commit hash 和 tag
• 后续建议：pip install build twine 准备 PyPI 发布 / 添加 README badges / GitHub Actions CI

常见坑（必查）

1. 不要把本地密码/凭据提交

   • 最常见错误：.env 含数据库密码 / API token
   • 不仅看当前工作区，还要全局扫描所有历史 commit：

     git grep -l "password|token|secret" $(git rev-list --all)
     

   • 如果误提交了密码，立即让用户去对应平台重置密码，然后用 git filter-repo 清理历史（见下方 Step 6）

2. Windows CRLF 警告是正常的

   • LF will be replaced by CRLF 是 Git for Windows 的默认行为，不影响功能
   • 不要为了消除警告乱改 core.autocrlf

3. bash 对特殊字符的处理

   • 密码 / 配置值含 ! $ 等字符时，不要直接拼在命令行字符串里
   • 用文件（.env）或单引号包裹

4. main vs master

   • 新仓库统一用 main（GitHub 默认）
   • 老仓库用 git branch -M main 重命名

5. 首次 push 认证

   • 推荐 gh auth login（浏览器一键授权）
   • 或用 Personal Access Token：Settings → Developer settings → Tokens (classic)，勾选 repo 权限

6. scripts/ 目录里硬编码的测试密码（Python/Node 项目）

   • 即使是测试数据库、本地开发用的密码，也不要硬编码在 scripts/、tests/ 里
   • 统一从环境变量读：os.getenv('MYSQL_PASSWORD', '')
   • 在 .gitignore 里确认 .env 已排除；.env.example 只放占位符

Step 6 — 历史敏感信息清理（git filter-repo）

如果发现敏感信息已经提交到历史：

pip install git-filter-repo

# 1. 创建替换规则文件 replace.txt（格式：旧字符串==>替换字符串）
cat > replace.txt <<'EOF'
your_real_password==>${DB_PASSWORD}
sk-xxxxx==>${OPENAI_API_KEY}
EOF

# 2. 备份（重要！filter-repo 会重写所有 commit hash）
cp -r . ../myproject-backup

# 3. 执行重写（filter-repo 会自动移除 origin）
git filter-repo --replace-text replace.txt --force

# 4. 验证
git grep -l "your_real_password" $(git rev-list --all) || echo "✅ 干净"

# 5. 重新添加 remote 并 force push
git remote add origin https://github.com//.git
git push --force origin main

# 6. 重建 tag（filter-repo 后 tag 指向旧 hash，需要删旧建新）
git tag -d vX.Y.Z
git tag -a vX.Y.Z -m "vX.Y.Z"
git push --force origin vX.Y.Z
# 删除远程旧 tag：git push origin :vX.Y.Z

注意：

• 重写历史后所有 collaborator 需要重新 clone（旧 commit hash 失效）
• 已发布到 PyPI/npm 的版本无法删除，但新版本会替代
• 公开仓库历史被抓过的话，敏感信息可能已被缓存（Google Cache、Internet Archive），所以改密码永远是第一步

Step 7 — 公开版本措辞

如果提交是为了修复敏感信息，commit message 和 tag message 绝不能提"密码/泄露/安全修复"。

错误示例：

security: fix hardcoded password leak ❌

正确示例（中性表述）：

refactor: improve configuration management ✅
chore: bump version to X.Y.Z

tag release notes 也用中性说法："improved configuration management"、"code cleanup"、"refined scripts"。

一键命令模板

# 1. 初始化（首次）
git init -b main

# 2. 补齐文件（根据项目类型）
# .gitignore / LICENSE / README 按需生成

# 3. 提交
git add .
git commit -m "feat: initial release"

# 4. 创建远程仓库并推送（需 gh CLI 已登录）
gh repo create  --public --source=. --remote=origin --push

# 5. 打 tag 推送
git tag -a v0.1.0 -m "v0.1.0" && git push origin v0.1.0

关联 skill

• pypi-upload — 如果是 Python 项目，推完 GitHub 后直接发布 PyPI