171 lines
4.4 KiB
Markdown
171 lines
4.4 KiB
Markdown
# 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)
|