CI/CD / 系统课时
权限不足导致失败怎么查
权限不足导致失败怎么查
流水线出现 403、Permission denied 或资源访问被拒绝时,不要先重跑任务。应沿着“工作流令牌 → Secrets → Environment → 外部服务”逐层确认凭据来自哪里、拥有什么权限,以及是否被事件来源或环境规则限制。
学习目标
- 能区分
GITHUB_TOKEN、Secrets、Environment 与外部服务凭据的权限边界 - 能根据失败位置按顺序定位授权问题
- 能用最小权限修复并验证流水线
先判断是谁拒绝了请求
权限故障首先看失败步骤和 HTTP 状态,而不是笼统地检查所有 Secrets。GitHub API 返回 403,通常应检查 GITHUB_TOKEN 或 PAT;云平台、镜像仓库等外部服务拒绝请求,则应检查对应凭据及服务端授权。
可以先在失败步骤附近搜索典型信息:403、Resource not accessible by integration、Permission denied、unauthorized。不要通过 echo 输出令牌验证 Secret 是否存在,日志脱敏不能替代安全控制。
检查 GITHUB_TOKEN 权限
GITHUB_TOKEN 由 GitHub Actions 为作业提供,其实际能力受仓库设置、事件类型和工作流 permissions 共同约束。若任务需要写入仓库内容,应显式声明所需的最小权限。
下面的诊断工作流读取仓库元数据,并演示如何明确授予 contents: read:
name: permission-check
on:
workflow_dispatch:
permissions:
contents: read
jobs:
check:
runs-on: ubuntu-latest
steps:
- name: Check repository access
env:
GH_TOKEN: ${{ github.token }}
run: gh api repos/${{ github.repository }} --jq '.full_name'预期输出
<OWNER>/<REPOSITORY>其中仓库名取决于实际运行环境。若后续步骤需要创建 release、提交内容或操作其他资源,应只增加对应权限,不要为了排障直接改成 write-all。
检查 Secrets 和环境规则
Secret 排查重点不是确认名称看起来正确,而是确认当前工作流是否处于它的可用作用域。依次检查 Secret 是仓库、组织还是 Environment 级别,以及作业是否声明了对应 environment。
如果部署凭据属于 production Environment,作业通常需要关联该环境:
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- name: Verify credential is available
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
run: |
if [ -z "$DEPLOY_TOKEN" ]; then
echo "DEPLOY_TOKEN is unavailable"
exit 1
fi
echo "DEPLOY_TOKEN is available"预期输出
DEPLOY_TOKEN is available这只验证变量是否可用,不泄露其内容。若作业停留在等待状态而非立即失败,还要检查 Environment 的审批或部署保护规则;这类问题与令牌本身无效是两条不同的排查路径。
检查外部服务授权
Secret 成功注入只说明 GitHub Actions 拿到了字符串,不代表外部系统接受它。云平台、容器仓库或部署平台仍可能因为令牌过期、角色不足、资源范围错误或服务端策略而拒绝请求。

因此最有效的顺序是:先确定拒绝请求的系统,再确认凭据是否进入当前作业,最后检查该凭据在目标系统中的授权范围。修复后重新运行同一操作,以原先失败的 API、上传或部署步骤成功作为验证,而不是仅以工作流变绿作为依据。