bruno
2cb4ddc4c0
Major Updates: - ✅ Implemented 4 Claude Code Skills (2600+ lines) - code-review: Security, quality, type checking - test-generator: Auto-generate pytest tests - doc-updater: Auto-update README and API docs - refactor-assistant: Code smell detection - ✅ Implemented 2 Git Hooks (450+ lines) - pre-commit: Auto-format, lint, review - pre-push: Test suite and coverage check - 📚 Complete documentation (20+ files) - Skills READMEs with examples - Optimization roadmap and progress - TODO list with 22 tasks - Quick reference guide - 📊 Progress: 45% → 64% (Phase 1: 20% → 60%) - 💰 ROI: Saving 50.6 hours/month ≈ 6.3 person-days/month Next Steps: - API Designer Skill - Code templates library - Prompt library - GitHub Projects task tracking 🤖 Generated with Claude Code Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
411 lines
8.4 KiB
Markdown
411 lines
8.4 KiB
Markdown
# GitHub Token 安全配置 - 快速入门
|
||
|
||
## 🎯 目标
|
||
|
||
安全地配置 GitHub Personal Access Token，用于项目管理脚本。
|
||
|
||
## ⚡ 最快方式（推荐）
|
||
|
||
### 使用配置向导（自动化）
|
||
|
||
```bash
|
||
# 运行配置向导
|
||
./scripts/setup-token.sh
|
||
```
|
||
|
||
向导会：
|
||
1. 检测你的操作系统
|
||
2. 检查现有配置
|
||
3. 推荐最佳配置方式
|
||
4. 自动完成配置
|
||
5. 测试验证
|
||
|
||
**预计时间：** 2-3 分钟
|
||
|
||
---
|
||
|
||
## 🚀 推荐配置方式
|
||
|
||
### 方式 1: GitHub CLI（最推荐）⭐⭐⭐⭐⭐
|
||
|
||
**优势：** 官方工具、自动管理、支持多账号
|
||
|
||
```bash
|
||
# 1. 安装 GitHub CLI
|
||
# macOS
|
||
brew install gh
|
||
|
||
# Linux
|
||
# 参考: https://cli.github.com/manual/installation
|
||
|
||
# Windows
|
||
winget install GitHub.cli
|
||
|
||
# 2. 登录
|
||
gh auth login
|
||
|
||
# 选择：
|
||
# > GitHub.com
|
||
# > HTTPS
|
||
# > Yes (authenticate Git with GitHub credentials)
|
||
# > Login with a web browser
|
||
|
||
# 3. 验证
|
||
gh auth status
|
||
|
||
# 4. 使用
|
||
# Token 会自动从 gh CLI 获取，无需额外配置
|
||
python3 scripts/setup-project-fields.py --project-id PVT_xxx
|
||
```
|
||
|
||
### 方式 2: 环境变量（简单直接）⭐⭐⭐⭐
|
||
|
||
#### macOS / Linux
|
||
|
||
**临时设置（当前终端）：**
|
||
```bash
|
||
export GITHUB_TOKEN="ghp_your_token_here"
|
||
```
|
||
|
||
**永久设置（推荐）：**
|
||
|
||
```bash
|
||
# Bash 用户
|
||
echo 'export GITHUB_TOKEN="ghp_your_token_here"' >> ~/.bashrc
|
||
source ~/.bashrc
|
||
|
||
# Zsh 用户
|
||
echo 'export GITHUB_TOKEN="ghp_your_token_here"' >> ~/.zshrc
|
||
source ~/.zshrc
|
||
|
||
# 验证
|
||
echo $GITHUB_TOKEN
|
||
```
|
||
|
||
#### Windows
|
||
|
||
**PowerShell（永久）：**
|
||
```powershell
|
||
[System.Environment]::SetEnvironmentVariable(
|
||
"GITHUB_TOKEN",
|
||
"ghp_your_token_here",
|
||
[System.EnvironmentVariableTarget]::User
|
||
)
|
||
|
||
# 重启 PowerShell 后验证
|
||
$env:GITHUB_TOKEN
|
||
```
|
||
|
||
### 方式 3: .env 文件（项目级）⭐⭐⭐⭐
|
||
|
||
```bash
|
||
# 1. 复制模板
|
||
cp .env.example .env
|
||
|
||
# 2. 编辑 .env
|
||
nano .env
|
||
|
||
# 修改为：
|
||
GITHUB_TOKEN=ghp_your_token_here
|
||
PROJECT_ID=PVT_kwDOAgn-Q84BLjWg
|
||
PROJECT_OWNER=BrunoGaoSZ
|
||
PROJECT_NUMBER=2
|
||
|
||
# 3. 确保安全
|
||
chmod 600 .env
|
||
|
||
# 4. 验证（.env 已在 .gitignore 中）
|
||
grep .env .gitignore
|
||
```
|
||
|
||
### 方式 4: macOS Keychain（macOS 用户）⭐⭐⭐⭐⭐
|
||
|
||
```bash
|
||
# 存储到 Keychain
|
||
security add-generic-password \
|
||
-s "GitHub Token - SDLC Management" \
|
||
-a "$(whoami)" \
|
||
-w "ghp_your_token_here" \
|
||
-U
|
||
|
||
# 验证
|
||
security find-generic-password \
|
||
-s "GitHub Token - SDLC Management" \
|
||
-a "$(whoami)" \
|
||
-w
|
||
|
||
# 使用（自动从 Keychain 读取）
|
||
python3 scripts/setup-project-fields.py --project-id PVT_xxx
|
||
```
|
||
|
||
### 方式 5: Linux pass（Linux 用户）⭐⭐⭐⭐⭐
|
||
|
||
```bash
|
||
# 安装 pass
|
||
sudo apt install pass
|
||
|
||
# 初始化（如果是首次使用）
|
||
gpg --full-generate-key
|
||
pass init your-gpg-key-id
|
||
|
||
# 存储 token
|
||
pass insert github/token-sdlc
|
||
# 输入 token
|
||
|
||
# 验证
|
||
pass github/token-sdlc
|
||
|
||
# 使用（自动从 pass 读取）
|
||
python3 scripts/setup-project-fields.py --project-id PVT_xxx
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 获取 GitHub Token
|
||
|
||
### 第一步：创建 Token
|
||
|
||
1. 访问：https://github.com/settings/tokens/new
|
||
2. 填写：
|
||
```
|
||
Note: SDLC Project Management - 2025
|
||
Expiration: 90 days (推荐)
|
||
```
|
||
3. 选择权限：
|
||
```
|
||
✅ repo
|
||
✅ project
|
||
✅ write:org (仅组织项目需要)
|
||
```
|
||
4. 点击 "Generate token"
|
||
5. **立即复制 token**（只显示一次！）
|
||
|
||
### 第二步：安全存储
|
||
|
||
**使用上述任一方式存储 token**
|
||
|
||
### 第三步：验证配置
|
||
|
||
```bash
|
||
# 使用测试工具
|
||
python3 scripts/get-github-token.py
|
||
|
||
# 应该输出：
|
||
# ✅ Token loaded from: [来源]
|
||
# Token: ghp_NTUSp...2xs
|
||
# ghp_your_full_token...
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠️ Token 获取工具
|
||
|
||
### 自动从多个来源获取
|
||
|
||
```bash
|
||
# 测试工具会按优先级尝试：
|
||
# 1. 环境变量 GITHUB_TOKEN
|
||
# 2. GitHub CLI (gh auth token)
|
||
# 3. macOS Keychain
|
||
# 4. Linux pass
|
||
# 5. 1Password CLI
|
||
# 6. .env 文件
|
||
|
||
python3 scripts/get-github-token.py
|
||
```
|
||
|
||
### 在其他脚本中使用
|
||
|
||
```bash
|
||
# 方式 1: 导出到环境变量
|
||
export GITHUB_TOKEN=$(python3 scripts/get-github-token.py)
|
||
|
||
# 方式 2: 直接传递
|
||
python scripts/setup-project-fields.py \
|
||
--token $(python3 scripts/get-github-token.py --quiet)
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 安全提醒
|
||
|
||
### ✅ 应该做的
|
||
|
||
- ✅ 使用 Fine-grained Token（而非 Classic）
|
||
- ✅ 设置 90 天过期时间
|
||
- ✅ 只授予必要的最小权限
|
||
- ✅ 使用密钥管理工具存储
|
||
- ✅ .env 文件加入 .gitignore
|
||
- ✅ 定期轮换 token
|
||
|
||
### ❌ 永远不要
|
||
|
||
- ❌ 硬编码在脚本中
|
||
- ❌ 提交到 Git 仓库
|
||
- ❌ 在命令行历史中暴露
|
||
- ❌ 在公开文档中分享
|
||
- ❌ 设置永不过期
|
||
- ❌ 授予过多权限
|
||
|
||
### 如果 Token 泄露
|
||
|
||
```bash
|
||
# 1. 立即撤销
|
||
# 访问: https://github.com/settings/tokens
|
||
# 找到并删除泄露的 token
|
||
|
||
# 2. 生成新 token
|
||
# 使用上述方法重新配置
|
||
|
||
# 3. 检查 Git 历史
|
||
git log -p | grep -i "ghp_"
|
||
|
||
# 4. 如果提交到了 Git，重写历史（危险操作！）
|
||
# 建议使用 BFG Repo-Cleaner
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 优先级说明
|
||
|
||
脚本会按以下顺序查找 token：
|
||
|
||
```
|
||
1. 命令行参数 --token (最高优先级)
|
||
↓
|
||
2. 环境变量 GITHUB_TOKEN
|
||
↓
|
||
3. GitHub CLI (gh auth token)
|
||
↓
|
||
4. macOS Keychain
|
||
↓
|
||
5. Linux pass
|
||
↓
|
||
6. 1Password CLI
|
||
↓
|
||
7. .env 文件 (最低优先级)
|
||
```
|
||
|
||
**推荐：** 使用 GitHub CLI 或系统密钥链（Keychain/pass）
|
||
|
||
---
|
||
|
||
## 📊 配置方式对比
|
||
|
||
| 方式 | 安全性 | 便利性 | 跨平台 | 推荐度 |
|
||
|------|--------|--------|--------|--------|
|
||
| **GitHub CLI** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ✅ | ⭐⭐⭐⭐⭐ |
|
||
| **macOS Keychain** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | macOS only | ⭐⭐⭐⭐⭐ |
|
||
| **Linux pass** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | Linux only | ⭐⭐⭐⭐⭐ |
|
||
| **环境变量** | ⭐⭐⭐ | ⭐⭐⭐⭐ | ✅ | ⭐⭐⭐⭐ |
|
||
| **.env 文件** | ⭐⭐ | ⭐⭐⭐⭐⭐ | ✅ | ⭐⭐⭐⭐ |
|
||
| **硬编码** | ❌ 危险 | ⭐⭐⭐⭐⭐ | ✅ | ❌ 永不使用 |
|
||
|
||
---
|
||
|
||
## 🎯 快速检查清单
|
||
|
||
配置完成后，检查：
|
||
|
||
- [ ] Token 已安全存储（非硬编码）
|
||
- [ ] 测试工具能获取到 token
|
||
```bash
|
||
python3 scripts/get-github-token.py
|
||
```
|
||
- [ ] .env 文件已加入 .gitignore（如使用）
|
||
- [ ] 配置文件权限正确（600）
|
||
- [ ] Token 有正确的权限（repo, project）
|
||
- [ ] 设置了过期时间（90 天）
|
||
- [ ] 记录了 token 用途和过期日期
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
### 快速参考
|
||
- **配置向导**: `./scripts/setup-token.sh`
|
||
- **测试工具**: `python3 scripts/get-github-token.py`
|
||
- **示例配置**: `.env.example`
|
||
|
||
### 详细文档
|
||
- **完整指南**: [docs/best-practices/github-token-management.md](docs/best-practices/github-token-management.md)
|
||
- **安全提醒**: [.github-token-security.md](.github-token-security.md)
|
||
- **项目管理**: [PROJECT-MANAGEMENT-SUMMARY.md](PROJECT-MANAGEMENT-SUMMARY.md)
|
||
|
||
### 官方资源
|
||
- **GitHub Token 文档**: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
|
||
- **GitHub CLI**: https://cli.github.com/manual/
|
||
- **Fine-grained PAT**: https://github.blog/2022-10-18-introducing-fine-grained-personal-access-tokens-for-github/
|
||
|
||
---
|
||
|
||
## 💡 故障排查
|
||
|
||
### 问题：脚本找不到 token
|
||
|
||
```bash
|
||
# 按优先级检查
|
||
echo "1. 环境变量: $GITHUB_TOKEN"
|
||
echo "2. GitHub CLI:"
|
||
gh auth status
|
||
echo "3. Keychain (macOS):"
|
||
security find-generic-password -s "GitHub Token - SDLC Management" -w
|
||
echo "4. .env 文件:"
|
||
cat .env | grep GITHUB_TOKEN
|
||
```
|
||
|
||
### 问题：Token 无效或过期
|
||
|
||
```bash
|
||
# 测试 token
|
||
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
|
||
https://api.github.com/user
|
||
|
||
# 如果返回 401，token 无效或过期
|
||
# 重新生成并配置新 token
|
||
```
|
||
|
||
### 问题：权限不足
|
||
|
||
```bash
|
||
# 检查 token 权限
|
||
gh auth status
|
||
|
||
# 或
|
||
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
|
||
https://api.github.com/user \
|
||
-I | grep "x-oauth-scopes"
|
||
|
||
# 需要包含: repo, project, (write:org)
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 现在就开始
|
||
|
||
```bash
|
||
# 1. 运行配置向导（最简单）
|
||
./scripts/setup-token.sh
|
||
|
||
# 2. 或手动配置环境变量
|
||
export GITHUB_TOKEN="your_token"
|
||
|
||
# 3. 或使用 GitHub CLI
|
||
gh auth login
|
||
|
||
# 4. 验证配置
|
||
python3 scripts/get-github-token.py
|
||
|
||
# 5. 开始使用
|
||
python3 scripts/setup-project-fields.py --project-id PVT_xxx
|
||
python3 scripts/generate-progress-report.py --project-id PVT_xxx
|
||
```
|
||
|
||
---
|
||
|
||
**创建时间**: 2024-12-30
|
||
**适用项目**: SDLC Management - Gold Template
|
||
**维护者**: DevOps Team
|
||
|
||
**需要帮助？** 查看完整文档：[docs/best-practices/github-token-management.md](docs/best-practices/github-token-management.md)
|