第1章 基础环境与仓库权限配置

GitHub Actions 的运行依赖一组底层基础设施：身份凭证、密钥存储、执行权限与计算节点。本章围绕这四个要素，建立可直接投入使用的初始环境。

原理概述

每个要素解决一个独立问题：

• 个人访问令牌（PAT） — 代表用户或应用向 GitHub API 发起请求的凭证，必须赋予 repo 与 workflow 权限才能操作 Actions。
• 仓库 Secrets — 将敏感信息（、密码）加密存储在仓库层面，工作流运行时自动解密注入，避免明文暴露。
• Actions 权限 — 仓库级别的开关，允许 Workflows 运行并调用第三方 Action。
• Runner — 实际执行作业的服务器，可以是 GitHub 托管的虚拟机或自托管机器。

实现流程

推荐按以下顺序配置，避免认证与权限冲突：

1. 生成个人访问令牌（PAT）并记录令牌字符串。
2. 将 PAT 添加到仓库 Secrets（命名为 MY_PAT）。
3. 在仓库设置中启用 Actions 权限（允许所有或指定 Action）。
4. 添加 Runner（选择 GitHub-hosted 或自托管）。
5. 使用最小工作流验证连通性。

详细操作

1. 创建个人访问令牌（PAT）

在 GitHub 上，进入 Settings → Developer settings → Personal access tokens → Tokens (classic) 生成经典令牌，或选择 Fine-grained PAT 获得精细权限控制。推荐使用经典 PAT 并勾选以下范围：

• repo（全部）
• workflow
• admin:org（如果需要管理组织 Runner）

使用 gh CLI 创建令牌（需要先登录）：

gh auth login
gh auth status
# 创建具有 repo 和 workflow 权限的令牌
gh auth  --scopes "repo,workflow"

2. 配置仓库 Secrets

将 PAT 作为 Secret 存入仓库，工作流中通过 ${{ secrets.MY_PAT }} 引用。

路径：仓库 → Settings → Secrets and variables → Actions → New repository secret。

名字建议：MY_PAT 或 GH_（注意不要与系统保留名冲突）。

也可以通过 GitHub CLI 设置：

gh secret set MY_PAT --repo owner/repo --body "ghp_xxxxxxxxxxxxxxxxxxxx"

3. 启用 Actions 权限

路径：仓库 → Settings → Actions → General。在 Actions permissions 区域选择：

• Allow all actions and reusable workflows（最宽松，适合测试）
• 或 Allow select actions 并添加可信第三方 Action。

还可以限制 Fork pull request workflows 的行为，建议测试阶段设置为 Require approval for all external contributions。

使用 API 检查当前 Actions 权限：

curl -s -H "Authorization: Bearer YOUR_PAT" \
  https://api.github.com/repos/owner/repo/actions/permissions

4. 添加 Runner

GitHub 提供托管 Runner（Ubuntu/Windows/macOS），也支持自托管 Runner。添加自托管 Runner 步骤：

1. 在仓库 → Settings → Actions → Runners 点击 New self-hosted runner。
2. 选择操作系统与架构（如 Linux x64）。
3. 复制页面中显示的注册命令，在目标机器执行：

# 创建目录并下载配置文件
mkdir actions-runner && cd actions-runner
curl -O -L https://github.com/actions/runner/releases/download/v2.317.0/actions-runner-linux-x64-2.317.0.tar.gz
tar xzf actions-runner-linux-x64-2.317.0.tar.gz

# 注册 Runner（使用前面生成的 PAT）
./config.sh --url https://github.com/owner/repo -- YOUR_REGISTRATION_

# 以服务方式运行
sudo ./svc.sh install
sudo ./svc.sh start

5. 验证连通

在仓库根目录创建 .github/workflows/test.yml：

name: Test Runner Connectivity
on: [push]
jobs:
  check:
    runs-on: [self-hosted, linux]  # 或 ubuntu-latest
    steps:
      - name: Print environment
        run: |
          echo "Runner: $(hostname)"
          echo "Actions version: $ACTIONS_RUNTIME_"

推送后查看 Workflow 执行日志，确认 Runner 成功接收作业。

调试与稳定性建议

• 令牌刷新：PAT 过期后工作流会失败，建议使用 Fine-grained PAT 并开启自动续期（需 GitHub Enterprise）。
• Secrets 轮换：定期更新 Secrets，避免长期暴露。
• Runner 健康监控：自托管 Runner 应添加心跳检查或使用 ./run.sh 守护进程。
• 权限最小化：Fine-grained PAT 仅授予必需仓库，减少泄露影响面。