ljwx-children/TOKEN-SETUP-QUICKSTART.md

GitHub Token 安全配置 - 快速入门

🎯 目标

安全地配置 GitHub Personal Access Token，用于项目管理脚本。

⚡ 最快方式（推荐）

使用配置向导（自动化）

# 运行配置向导
./scripts/setup-token.sh

向导会：

1. 检测你的操作系统
2. 检查现有配置
3. 推荐最佳配置方式
4. 自动完成配置
5. 测试验证

预计时间： 2-3 分钟

---

🚀 推荐配置方式

方式 1: GitHub CLI（最推荐）⭐⭐⭐⭐⭐

优势： 官方工具、自动管理、支持多账号

# 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

临时设置（当前终端）：

export GITHUB_TOKEN="ghp_your_token_here"

永久设置（推荐）：

# 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（永久）：

[System.Environment]::SetEnvironmentVariable(
    "GITHUB_TOKEN",
    "ghp_your_token_here",
    [System.EnvironmentVariableTarget]::User
)

# 重启 PowerShell 后验证
$env:GITHUB_TOKEN

方式 3: .env 文件（项目级）⭐⭐⭐⭐

# 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 用户）⭐⭐⭐⭐⭐

# 存储到 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 用户）⭐⭐⭐⭐⭐

# 安装 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

第三步：验证配置

# 使用测试工具
python3 scripts/get-github-token.py

# 应该输出：
# ✅ Token loaded from: [来源]
#    Token: ghp_NTUSp...2xs
# ghp_your_full_token...

---

🛠️ Token 获取工具

自动从多个来源获取

# 测试工具会按优先级尝试：
# 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

在其他脚本中使用

# 方式 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 泄露

# 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

  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
• 安全提醒: .github-token-security.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

# 按优先级检查
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 无效或过期

# 测试 token
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/user

# 如果返回 401，token 无效或过期
# 重新生成并配置新 token

问题：权限不足

# 检查 token 权限
gh auth status

# 或
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/user \
  -I | grep "x-oauth-scopes"

# 需要包含: repo, project, (write:org)

---

🚀 现在就开始

# 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