配置云端开发环境

cloud agent 在临时 GitHub Actions 环境中工作。通过 setup steps 提前安装项目依赖，可以让它直接构建和测试，减少每次任务重新猜测安装步骤的时间。

文件与执行前提

在仓库中创建：

.github/workflows/copilot-setup-steps.yml

文件必须包含唯一一个名为 copilot-setup-steps 的 job；它的 steps 在代理开始工作前执行。文件必须存在于默认分支，工作流才会触发。不要仅提交到临时分支后，就假定云端任务已经使用该配置。

可调整字段

官方只允许定制该 job 的以下设置，其他 job 设置会被忽略：

完整字段含义还需遵循 GitHub Actions 语法。代理本身使用另外的 token；为 setup steps 设置 permissions 不等于直接改变代理的全部操作权限。

一个 Node.js 初始化示例

下面基于官方示例，仅保留手动验证触发器和安装步骤。Node.js 20 是该示例的选择，不是所有 cloud agent 项目的统一版本要求。

name: "Copilot Setup Steps"
on:
  workflow_dispatch:
jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "20"
          cache: "npm"
      - name: Install JavaScript dependencies
        run: npm ci

按项目实际语言、版本和锁文件修改依赖步骤。若不在 setup steps 中 checkout，Copilot 会在这些步骤结束后自行检出代码；若需要先安装仓库依赖，通常就需要如示例那样 checkout，并提供 contents: read。

actions/checkout 的 fetch-depth 值会被系统覆盖，以支持回退提交并控制风险，不能依赖自己设定的深度值始终有效。

验证与失败行为

将文件合入默认分支后，可以从 Actions 手动运行，检查初始化是否成功；也可按需要添加针对文件变更的 push 或 pull_request 触发器。只有配置对应触发器，才能依赖相应事件自动验证。

真实代理运行时，setup 过程会出现在会话日志中。某一步返回非零退出码后，剩余 setup steps 会被跳过，但代理仍会按当前环境状态开始工作。 因此初始化失败不等于整个任务已被阻止；应检查日志，而不是只看任务最终是否有输出。

Git LFS

使用 LFS 的仓库需要准备 Git LFS 并获取对象。官方给出的 checkout 配置为：

- uses: actions/checkout@v6
  with:
    lfs: true

将其放到 copilot-setup-steps 的 steps 中，并保留所需读取权限。Runner 和 Windows 支持见运行器配置，私有依赖凭据见Secrets 与变量。

与 code review 的关系

Copilot code review 默认复用 copilot-setup-steps.yml，也支持专门的 copilot-code-review.yml 来独立配置环境。不要假定修改共享 setup 文件只影响 cloud agent。

代码审查的平台范围应单独按审查 runner核对，不能由 cloud agent 的 Windows 支持推断。