ljwx-children/docs/best-practices/github-token-management.md

GitHub Token 安全管理完全指南

🎯 概述

本指南提供 GitHub Personal Access Token (PAT) 的安全管理最佳实践，包括生成、存储、使用和撤销的完整流程。

📋 目录

• 生成 Token
• 存储方式对比
• 环境变量配置
• 项目级配置
• 密钥管理工具
• GitHub CLI 方式
• 安全检查清单
• 故障排查

---

生成 Token

第一步：创建 Token

1. 访问：https://github.com/settings/tokens/new

2. 填写信息：

   Note: SDLC Project Management - 2025
   Expiration: 90 days (推荐)
   

3. 选择权限（最小权限原则）：

   基础配置（项目管理）：

   ✅ repo
      ✅ repo:status
      ✅ public_repo (如果只需要公开仓库)
   
   ✅ project
      ✅ read:project
      ✅ write:project
   
   ✅ write:org (仅组织级项目需要)
      ✅ read:org
   

   高级配置（自动化）：

   ✅ workflow (如果需要触发 GitHub Actions)
   ✅ admin:repo_hook (如果需要管理 webhooks)
   

4. 点击 "Generate token"

5. 立即复制 token - 只显示一次！

Token 格式

Classic Token: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (40 字符)
Fine-grained Token: github_pat_xxxxxxxxxxxxx... (更长，推荐)

Fine-grained vs Classic Token

特性	Fine-grained Token (新)	Classic Token (旧)
粒度	✅ 可精确到仓库	❌ 全局权限
过期	✅ 强制过期	⚠️ 可永不过期
安全性	✅ 更高	⚠️ 较低
可撤销性	✅ 更细粒度	❌ 全部撤销
推荐度	⭐⭐⭐⭐⭐	⭐⭐⭐

推荐使用 Fine-grained Token！

---

存储方式对比

方式对比表

方式	安全性	便利性	适用场景	推荐度
环境变量 (.bashrc)	⭐⭐⭐	⭐⭐⭐⭐	个人开发机	⭐⭐⭐⭐
.env 文件	⭐⭐	⭐⭐⭐⭐⭐	项目级配置	⭐⭐⭐⭐
系统密钥链 (Keychain)	⭐⭐⭐⭐⭐	⭐⭐⭐	macOS 用户	⭐⭐⭐⭐⭐
pass (密码管理器)	⭐⭐⭐⭐⭐	⭐⭐⭐	Linux 用户	⭐⭐⭐⭐⭐
GitHub CLI	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	所有场景	⭐⭐⭐⭐⭐
1Password CLI	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	团队协作	⭐⭐⭐⭐⭐
硬编码	❌ 危险	⭐⭐⭐⭐⭐	永不使用	❌

❌ 永远不要这样做

# 1. 硬编码在脚本中
TOKEN="ghp_xxxxx"

# 2. 提交到 Git
git add .env
git commit -m "Add token"

# 3. 在命令行历史中暴露
python script.py --token ghp_xxxxx

# 4. 在公开的文档中
# README.md
export GITHUB_TOKEN="ghp_xxxxx"

---

环境变量配置

方式 1: Shell 配置文件（推荐）⭐⭐⭐⭐

macOS / Linux

Bash 用户 (~/.bashrc 或 ~/.bash_profile):

# 编辑配置文件
nano ~/.bashrc

# 添加以下内容
export GITHUB_TOKEN="ghp_your_token_here"

# 保存后重新加载
source ~/.bashrc

# 验证
echo $GITHUB_TOKEN

Zsh 用户 (~/.zshrc):

# 编辑配置文件
nano ~/.zshrc

# 添加以下内容
export GITHUB_TOKEN="ghp_your_token_here"

# 保存后重新加载
source ~/.zshrc

# 验证
echo $GITHUB_TOKEN

Fish 用户 (~/.config/fish/config.fish):

# 编辑配置文件
nano ~/.config/fish/config.fish

# 添加以下内容
set -gx GITHUB_TOKEN "ghp_your_token_here"

# 保存后重新加载
source ~/.config/fish/config.fish

# 验证
echo $GITHUB_TOKEN

Windows

PowerShell (永久):

# 设置用户级环境变量
[System.Environment]::SetEnvironmentVariable(
    "GITHUB_TOKEN",
    "ghp_your_token_here",
    [System.EnvironmentVariableTarget]::User
)

# 验证（需重启 PowerShell）
$env:GITHUB_TOKEN

PowerShell (临时):

# 仅当前会话有效
$env:GITHUB_TOKEN = "ghp_your_token_here"

# 验证
$env:GITHUB_TOKEN

CMD:

# 设置用户级环境变量
setx GITHUB_TOKEN "ghp_your_token_here"

# 验证（需重启 CMD）
echo %GITHUB_TOKEN%

通过 GUI 设置（Windows）:

1. 右键 "此电脑" → "属性"
2. "高级系统设置" → "环境变量"
3. 用户变量 → "新建"
4. 变量名：GITHUB_TOKEN
5. 变量值：ghp_your_token_here
6. 确定

方式 2: 临时环境变量

适用于一次性操作或测试：

# Linux/macOS - 仅当前终端会话有效
export GITHUB_TOKEN="ghp_your_token_here"

# 使用后立即删除
unset GITHUB_TOKEN

# 或在命令前临时设置
GITHUB_TOKEN="ghp_xxx" python scripts/setup-project-fields.py --project-id PVT_xxx

方式 3: 会话级别（更安全）

# 从安全存储读取（一次性）
read -s GITHUB_TOKEN
# 输入 token（不会显示）

# 或从文件读取
export GITHUB_TOKEN=$(cat ~/.github-token)

# 使用完后立即删除
unset GITHUB_TOKEN

环境变量安全加固

1. 限制文件权限

# 确保配置文件只有所有者可读写
chmod 600 ~/.bashrc
chmod 600 ~/.zshrc
chmod 600 ~/.config/fish/config.fish

# 验证权限
ls -la ~/.bashrc
# 应该显示: -rw------- (600)

2. 避免在历史中暴露

# 临时禁用历史记录
set +o history

# 设置 token
export GITHUB_TOKEN="ghp_xxx"

# 重新启用历史记录
set -o history

# 或使用空格前缀（部分 shell 支持）
 export GITHUB_TOKEN="ghp_xxx"  # 注意开头的空格

3. 清理命令历史

# 查看历史中是否有 token
history | grep -i "ghp_"
history | grep -i "token"

# 删除特定历史条目
history -d <行号>

# 清空所有历史
history -c

# 清空历史文件
> ~/.bash_history
# 或
> ~/.zsh_history

---

项目级配置

方式 1: .env 文件（推荐）⭐⭐⭐⭐⭐

创建 .env 文件

# 在项目根目录创建 .env
cat > .env << 'EOF'
# GitHub Token for project management
GITHUB_TOKEN=ghp_your_token_here

# Optional: Project-specific configuration
PROJECT_ID=PVT_kwDOAgn-Q84BLjWg
PROJECT_OWNER=BrunoGaoSZ
PROJECT_NUMBER=2
EOF

# 设置权限（只有所有者可读写）
chmod 600 .env

加入 .gitignore

# 确保 .env 不会被提交
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore
echo ".env.*.local" >> .gitignore

# 提交 .gitignore
git add .gitignore
git commit -m "Add .env to .gitignore"

创建 .env.example 模板

# 创建示例文件（不包含真实 token）
cat > .env.example << 'EOF'
# GitHub Token for project management
# Get token at: https://github.com/settings/tokens/new
GITHUB_TOKEN=your_github_token_here

# Project Configuration
PROJECT_ID=your_project_id
PROJECT_OWNER=your_org_or_username
PROJECT_NUMBER=1
EOF

# 提交模板供团队成员参考
git add .env.example
git commit -m "Add .env.example template"

在脚本中使用 .env

Python 方式（使用 python-dotenv）:

# 1. 安装依赖
# pip install python-dotenv

# 2. 在脚本中加载
from dotenv import load_dotenv
import os

# 加载 .env 文件
load_dotenv()

# 读取环境变量
token = os.getenv('GITHUB_TOKEN')
project_id = os.getenv('PROJECT_ID')

if not token:
    raise ValueError("GITHUB_TOKEN not found in .env file")

print(f"Token loaded: {token[:10]}...")  # 只显示前10个字符

Bash 方式:

#!/bin/bash

# 加载 .env 文件
if [ -f .env ]; then
    export $(cat .env | grep -v '^#' | xargs)
else
    echo "Error: .env file not found"
    exit 1
fi

# 使用环境变量
echo "Using token: ${GITHUB_TOKEN:0:10}..."
python scripts/setup-project-fields.py --project-id $PROJECT_ID

方式 2: direnv（自动化环境变量）⭐⭐⭐⭐⭐

什么是 direnv？

• 进入项目目录自动加载 .envrc
• 离开目录自动卸载
• 更安全、更便捷

安装 direnv:

# macOS
brew install direnv

# Linux (Debian/Ubuntu)
sudo apt install direnv

# 配置 shell hook
# Bash
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

# Fish
echo 'direnv hook fish | source' >> ~/.config/fish/config.fish

# 重新加载配置
source ~/.bashrc  # 或对应的配置文件

创建 .envrc:

# 在项目目录创建 .envrc
cat > .envrc << 'EOF'
# Load .env file
dotenv

# Or manually export variables
export GITHUB_TOKEN=ghp_your_token_here
export PROJECT_ID=PVT_kwDOAgn-Q84BLjWg
EOF

# 授权 direnv 加载此文件
direnv allow .

# 加入 .gitignore
echo ".envrc" >> .gitignore

使用效果:

# 进入项目目录 → 自动加载环境变量
cd ~/work/codes/opensource/gold-template
direnv: loading .envrc
direnv: export +GITHUB_TOKEN +PROJECT_ID

# 验证
echo $GITHUB_TOKEN
# ghp_xxx...

# 离开目录 → 自动卸载
cd ..
direnv: unloading
echo $GITHUB_TOKEN
# (空)

---

密钥管理工具

macOS: Keychain（推荐）⭐⭐⭐⭐⭐

存储 Token

# 添加到 Keychain
security add-generic-password \
  -s "GitHub Token - SDLC Management" \
  -a "$(whoami)" \
  -w "ghp_your_token_here" \
  -U

# 参数说明:
# -s: 服务名称（可自定义）
# -a: 账户名（当前用户）
# -w: 密码（token）
# -U: 更新已存在的条目

读取 Token

# 方式 1: 直接读取
security find-generic-password \
  -s "GitHub Token - SDLC Management" \
  -a "$(whoami)" \
  -w

# 方式 2: 存入环境变量
export GITHUB_TOKEN=$(security find-generic-password \
  -s "GitHub Token - SDLC Management" \
  -a "$(whoami)" \
  -w)

# 方式 3: 在脚本中使用
TOKEN=$(security find-generic-password \
  -s "GitHub Token - SDLC Management" \
  -a "$(whoami)" \
  -w)

python scripts/setup-project-fields.py --token "$TOKEN"

删除 Token

security delete-generic-password \
  -s "GitHub Token - SDLC Management" \
  -a "$(whoami)"

在 Python 中使用 Keychain

import subprocess
import sys

def get_token_from_keychain(service_name):
    """从 macOS Keychain 读取 token"""
    try:
        token = subprocess.check_output([
            'security', 'find-generic-password',
            '-s', service_name,
            '-a', subprocess.check_output(['whoami']).decode().strip(),
            '-w'
        ]).decode().strip()
        return token
    except subprocess.CalledProcessError:
        print(f"Error: Token not found in Keychain for service: {service_name}")
        sys.exit(1)

# 使用
token = get_token_from_keychain("GitHub Token - SDLC Management")

Linux: pass（密码管理器）⭐⭐⭐⭐⭐

安装和初始化

# 安装 pass
sudo apt install pass  # Debian/Ubuntu
sudo yum install pass  # RHEL/CentOS
brew install pass      # macOS

# 初始化（需要 GPG key）
pass init your-gpg-key-id

# 如果没有 GPG key，先创建
gpg --full-generate-key

存储 Token

# 存储 token
pass insert github/token-sdlc
# 输入 token（两次确认）

# 或从文件读取
cat token.txt | pass insert -m github/token-sdlc

读取 Token

# 方式 1: 直接显示
pass github/token-sdlc

# 方式 2: 存入环境变量
export GITHUB_TOKEN=$(pass github/token-sdlc)

# 方式 3: 在脚本中使用
TOKEN=$(pass github/token-sdlc)
python scripts/setup-project-fields.py --token "$TOKEN"

删除 Token

pass rm github/token-sdlc

跨平台: 1Password CLI ⭐⭐⭐⭐⭐

安装

# macOS
brew install --cask 1password-cli

# Linux
# 参考: https://developer.1password.com/docs/cli/get-started/

# Windows
# 下载: https://1password.com/downloads/command-line/

存储 Token

# 登录 1Password
op signin

# 创建项目并存储 token
op item create \
  --category="API Credential" \
  --title="GitHub Token - SDLC" \
  --vault="Development" \
  token="ghp_your_token_here"

读取 Token

# 方式 1: 直接读取
op item get "GitHub Token - SDLC" --fields token

# 方式 2: 存入环境变量
export GITHUB_TOKEN=$(op item get "GitHub Token - SDLC" --fields token)

# 方式 3: 在命令中使用（推荐）
python scripts/setup-project-fields.py \
  --token $(op item get "GitHub Token - SDLC" --fields token)

---

GitHub CLI 方式

最推荐的方式 ⭐⭐⭐⭐⭐

优势：

• ✅ GitHub 官方工具
• ✅ 自动安全存储
• ✅ 支持多账号
• ✅ 自动刷新
• ✅ 跨平台一致

安装 GitHub CLI

# macOS
brew install gh

# Linux (Debian/Ubuntu)
type -p curl >/dev/null || sudo apt install curl -y
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
&& sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y

# Windows
winget install --id GitHub.cli
# 或使用 Scoop
scoop install gh

登录和认证

# 方式 1: 通过浏览器登录（推荐）
gh auth login

# 选择：
# > GitHub.com
# > HTTPS
# > Yes (authenticate Git with GitHub credentials)
# > Login with a web browser

# 方式 2: 使用已有 token
gh auth login --with-token < token.txt
# 或
echo "ghp_your_token" | gh auth login --with-token

使用 gh CLI

# 查看认证状态
gh auth status

# 使用 API（自动使用存储的 token）
gh api user
gh api repos/:owner/:repo/issues

# 在脚本中使用 gh 的 token
export GITHUB_TOKEN=$(gh auth token)
python scripts/setup-project-fields.py --project-id PVT_xxx

多账号管理

# 添加多个账号
gh auth login --hostname github.com --web
gh auth login --hostname github.company.com --web

# 切换账号
gh auth switch

# 查看所有账号
gh auth status --show-token

gh CLI + 脚本集成

修改脚本使用 gh token:

#!/usr/bin/env python3
import subprocess
import os
import sys

def get_github_token():
    """优先级顺序获取 GitHub Token"""

    # 1. 尝试从环境变量
    token = os.getenv('GITHUB_TOKEN')
    if token:
        return token

    # 2. 尝试从 gh CLI
    try:
        token = subprocess.check_output(
            ['gh', 'auth', 'token'],
            stderr=subprocess.DEVNULL
        ).decode().strip()
        if token:
            return token
    except (subprocess.CalledProcessError, FileNotFoundError):
        pass

    # 3. 尝试从 macOS Keychain
    if sys.platform == 'darwin':
        try:
            token = subprocess.check_output([
                'security', 'find-generic-password',
                '-s', 'GitHub Token - SDLC Management',
                '-a', subprocess.check_output(['whoami']).decode().strip(),
                '-w'
            ]).decode().strip()
            if token:
                return token
        except subprocess.CalledProcessError:
            pass

    # 4. 尝试从 pass (Linux)
    try:
        token = subprocess.check_output(
            ['pass', 'github/token-sdlc'],
            stderr=subprocess.DEVNULL
        ).decode().strip()
        if token:
            return token
    except (subprocess.CalledProcessError, FileNotFoundError):
        pass

    # 5. 都失败了
    print("❌ Error: GitHub token not found!")
    print("   Try one of:")
    print("   - Set GITHUB_TOKEN environment variable")
    print("   - Run: gh auth login")
    print("   - Store in Keychain/pass")
    sys.exit(1)

# 使用
token = get_github_token()
print(f"✅ Token loaded from: {source}")

---

安全检查清单

✅ Token 生成

• 使用 Fine-grained Token（而非 Classic）
• 设置过期时间（推荐 90 天）
• 只授予必要的最小权限
• Token 名称清晰（包含用途和日期）
• 立即复制并安全存储

✅ Token 存储

• 使用以下安全方式之一：

  • GitHub CLI (gh auth login)
  • 系统密钥链 (Keychain/pass)
  • 1Password CLI
  • 环境变量 (shell 配置文件)
  • .env 文件（已加入 .gitignore）

• 限制文件权限为 600

• 未硬编码在脚本中

• 未提交到 Git 仓库

✅ Token 使用

• 脚本使用环境变量而非参数传递
• 命令历史中无 token 暴露
• 日志输出中不显示完整 token
• 使用后及时清理临时变量

✅ 仓库安全

• .gitignore 包含 .env, .envrc, *.token
• 提供 .env.example 模板
• Git 历史中无 token 泄露
• README 中使用变量占位符而非真实 token

✅ 定期维护

• 设置 Token 过期提醒
• 定期轮换 Token（每 90 天）
• 审查 Token 权限（是否仍需要）
• 删除不再使用的 Token

---

故障排查

问题 1: Token 未生效

# 检查环境变量是否设置
echo $GITHUB_TOKEN

# 检查 token 格式
echo $GITHUB_TOKEN | wc -c
# Classic token: 41 字符（包含换行）
# Fine-grained: 更长

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

问题 2: 权限不足

# 查看 token 权限
gh auth status

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

问题 3: Token 过期

# 检查 token 是否过期
gh auth status

# 刷新 token
gh auth refresh

# 或重新登录
gh auth login

问题 4: 多个 Token 冲突

# 检查所有可能的来源
echo "ENV: $GITHUB_TOKEN"
gh auth token
security find-generic-password -s "GitHub Token" -w
pass github/token-sdlc

# 清理冲突
unset GITHUB_TOKEN  # 清除环境变量
gh auth logout      # 登出 gh CLI

问题 5: .env 文件未加载

# 检查文件是否存在
ls -la .env

# 检查权限
stat .env

# 手动加载测试
source .env
echo $GITHUB_TOKEN

# Python 检查
python3 -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.getenv('GITHUB_TOKEN'))"

---

推荐配置方案

个人开发（单人）

推荐组合:
1. GitHub CLI (gh auth login) ⭐⭐⭐⭐⭐
2. 项目 .env 文件（开发时）
3. macOS Keychain / Linux pass（备份）

配置步骤:

# 1. 安装并登录 gh CLI
brew install gh
gh auth login

# 2. 项目中创建 .env
cat > .env << 'EOF'
GITHUB_TOKEN=$(gh auth token)
EOF

# 3. 加入 .gitignore
echo ".env" >> .gitignore

# 4. 使用
python scripts/setup-project-fields.py --project-id PVT_xxx

团队协作

推荐组合:
1. 每个成员使用 gh auth login
2. 项目 .env.example 模板
3. CI/CD 使用 Repository Secrets

CI/CD 配置 (GitHub Actions):

# .github/workflows/update-project.yml
name: Update Project
on:
  schedule:
    - cron: '0 0 * * 0'  # 每周日运行

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run update script
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # 使用内置 token
        run: |
          python scripts/generate-progress-report.py \
            --project-id ${{ secrets.PROJECT_ID }} \
            --output docs/reports/weekly-report.md

生产环境

推荐组合:
1. 密钥管理服务 (AWS Secrets Manager / HashiCorp Vault)
2. 环境变量注入（Kubernetes Secrets）
3. 短期 Token + 自动轮换

---

参考资源

官方文档

• 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/

工具文档

• direnv: https://direnv.net/
• pass: https://www.passwordstore.org/
• 1Password CLI: https://developer.1password.com/docs/cli/
• python-dotenv: https://pypi.org/project/python-dotenv/

最佳实践

• OWASP 密钥管理: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
• 12-Factor App: https://12factor.net/config

---

最后更新: 2024-12-30 维护者: DevOps Team 版本: 1.0.0

快速链接: Token 安全提醒 | 项目管理总结