GitHub Actions工作流创建环境遇403权限问题如何解决？

问题分析 #

你遇到的403错误是因为github.token默认没有环境操作权限，即使设置permissions: write-all也可能因为权限覆盖逻辑或默认限制未生效，需要明确指定必要的权限。

解决方案 #

1. 显式声明必要权限

在工作流的顶层或目标job中添加environments: write权限，这是创建/更新环境的核心权限，同时可搭配repository-administration: write确保仓库层面的操作权限：

permissions:
  environments: write
  repository-administration: write

2. 修正命令中的仓库路径

使用GitHub内置变量${{ github.repository }}代替手动拼接的$org/$repo，避免变量未正确赋值的问题，同时简化命令：

- name: Create test environment
  env:
    GH_TOKEN: ${{ github.token }}
  run: |
    gh api -X PUT \
      -H 'Accept: application/vnd.github+json' \
      -H 'X-GitHub-Api-Version: 2022-11-28' \
      /repos/${{ github.repository }}/environments/tst

完整工作流示例

name: Auto Create Environment

on: [workflow_dispatch]

# 全局权限配置，对所有job生效
permissions:
  environments: write
  repository-administration: write

jobs:
  setup-env:
    runs-on: ubuntu-latest
    steps:
      - name: Create tst environment
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh api -X PUT \
            -H 'Accept: application/vnd.github+json' \
            -H 'X-GitHub-Api-Version: 2022-11-28' \
            /repos/${{ github.repository }}/environments/tst

关键说明 #

• 不要依赖write-all：GitHub的write-all权限并非在所有场景下都能正确覆盖环境操作权限，显式声明environments: write是最可靠的方式。
• 权限作用范围：如果仅单个job需要该权限，可将permissions配置放在job内部，而非工作流顶层，更符合最小权限原则。
• 触发权限验证：确保工作流的触发者拥有仓库管理员级别的权限，否则即使配置了token权限，也可能因用户权限不足失败。

内容的提问来源于stack exchange，提问作者Guillaume