# GitHub Personal Access Token 权限配置指南

## 问题：`refusing to allow a Personal Access Token to create or update workflow`

### 原因

GitHub 要求推送 `.github/workflows/` 目录下的文件时，Personal Access Token 必须包含 `workflow` 权限。

### 解决方案

## 方案一：更新 Token 权限（推荐）

### 步骤 1：创建新的 Personal Access Token

1. 访问：https://github.com/settings/tokens
2. 点击 **Generate new token (classic)**
3. 填写 Token 名称：`wecom-ai-assistant-full-access`
4. 选择过期时间：根据你的需求（推荐 90 天或 No expiration）
5. **选择以下权限**：
   - ✅ **repo**（完整仓库访问权限）
     - ✅ repo:status
     - ✅ repo_deployment
     - ✅ public_repo
     - ✅ repo:invite
     - ✅ security_events
   - ✅ **workflow**（工作流权限）**← 必需**
   - ✅ **write:packages**（推送 Docker 镜像到 GHCR）
   - ✅ **read:packages**（从 GHCR 拉取镜像）
6. 点击 **Generate token**
7. **立即复制 token**（只显示一次）

### 步骤 2：更新配置文件

编辑 `.github-config` 文件，更新 token：

```bash
GITHUB_TOKEN=你的新token
```

### 步骤 3：更新 Git 远程 URL

```powershell
# 使用新 token 更新远程 URL
git remote set-url origin https://bujie9527:你的新token@github.com/bujie9527/wecom-ai-assistant.git

# 验证
git remote -v

# 重新推送
git push -u origin main
```

## 方案二：临时跳过 Workflow 文件（快速解决）

如果暂时不想更新 token，可以先推送其他文件：

### 步骤 1：移除 workflow 文件从暂存区

```powershell
# 从暂存区移除 workflow 文件
git reset HEAD .github/workflows/

# 提交其他文件
git commit -m "Initial commit: 企业微信 AI 机器人助理 MVP (without workflows)"

# 推送
git push -u origin main
```

### 步骤 2：稍后单独推送 workflow 文件

更新 token 后：

```powershell
# 添加 workflow 文件
git add .github/workflows/

# 提交
git commit -m "Add GitHub Actions workflows"

# 推送
git push origin main
```

## 方案三：使用 GitHub CLI（gh）

如果安装了 GitHub CLI：

```powershell
# 安装 GitHub CLI（如果还没有）
# 下载：https://cli.github.com/

# 登录（会自动处理权限）
gh auth login

# 推送代码
git push -u origin main
```

## Token 权限说明

### 必需权限

| 权限 | 说明 | 用途 |
|------|------|------|
| `repo` | 完整仓库访问 | 推送代码、创建分支等 |
| `workflow` | 工作流权限 | 推送 `.github/workflows/` 文件 |
| `write:packages` | 写入包 | 推送 Docker 镜像到 GHCR |
| `read:packages` | 读取包 | 从 GHCR 拉取镜像 |

### 权限范围

- **Full control of private repositories**：如果你使用私有仓库
- **Public repositories only**：如果使用公开仓库

## 验证 Token 权限

推送成功后，检查：

1. **仓库文件**：https://github.com/bujie9527/wecom-ai-assistant
2. **Workflow 文件**：https://github.com/bujie9527/wecom-ai-assistant/tree/main/.github/workflows
3. **Actions**：https://github.com/bujie9527/wecom-ai-assistant/actions

## 安全建议

1. **Token 安全**：
   - 不要将 token 提交到 Git
   - 定期轮换 token（每 90 天）
   - 如果 token 泄露，立即撤销

2. **最小权限原则**：
   - 只授予必要的权限
   - 使用 Fine-grained tokens（如果可用）限制仓库范围

3. **Token 存储**：
   - 存储在 `.github-config`（已添加到 `.gitignore`）
   - 或使用环境变量
   - 或使用 Git Credential Manager

## 故障排查

### 问题：仍然提示权限不足

**解决方案**：
1. 确认 token 已更新并包含 `workflow` 权限
2. 清除 Git 凭据缓存：
   ```powershell
   git credential-manager-core erase
   git credential reject https://github.com
   ```
3. 重新推送

### 问题：Token 在哪里查看/更新？

**答案**：
- 查看现有 tokens：https://github.com/settings/tokens
- 创建新 token：https://github.com/settings/tokens/new

### 问题：如何撤销旧 Token？

**答案**：
1. 访问：https://github.com/settings/tokens
2. 找到对应的 token
3. 点击 **Revoke**（撤销）

## 相关文档

- [GitHub Token 文档](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
- [GitHub Actions 权限](https://docs.github.com/en/actions/security-guides/automatic-token-authentication)
- [项目 Git 配置指南](./github-config-guide.md)