Copilot Cloud Agent 在 GitHub Actions 环境中执行任务。通过创建 copilot-setup-steps.yml 工作流文件，可以预装依赖、指定更大的 Runner、配置 Git LFS，让 Agent 在任务开始前就拥有完整的运行环境，减少执行中断。

GitHub Copilot Cloud Agent 环境配置：预装依赖和自定义 Runner

为什么需要配置环境

Copilot Cloud Agent 运行在隔离的 GitHub Actions 环境中。如果你的项目需要特定的 Node.js 版本、Python 依赖或其他工具，不提前配置的话，Agent 每次执行任务时都可能因为缺少依赖而失败。

配置文件位置

创建文件：.github/workflows/copilot-setup-steps.yml

关键要求：job 名称必须是 copilot-setup-steps，否则 Copilot 不会识别。

完整配置示例

name: "Copilot Setup Steps"
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout 代码
        uses: actions/checkout@v6

      - name: 安装 Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - name: 安装 npm 依赖
        run: npm ci

使用更大或自托管的 Runner

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-4-core   # 4 核 Ubuntu

jobs:
  copilot-setup-steps:
    runs-on: arc-scale-set-name  # 自托管 Runner

使用自托管 Runner 时，可能需要：

• 配置网络访问
• 禁用 Copilot 内置防火墙（见防火墙配置文档）

使用 Windows 环境

jobs:
  copilot-setup-steps:
    runs-on: windows-latest

启用 Git LFS

jobs:
  copilot-setup-steps:
    steps:
      - uses: actions/checkout@v6
        with:
          lfs: true

配置环境变量和 Secrets

Agent 执行时可能需要 API Keys 或代理设置：

1. 进入仓库 Settings → Environments
2. 创建或选择 copilot 环境
3. 添加环境变量（Environment variables）或密钥（Environment secrets）

Secrets 命名建议：MCP 相关的 Secrets 用 COPILOT_MCP_ 前缀（如 COPILOT_MCP_NOTION_API_KEY）。

可配置的字段

字段	说明
steps	预安装步骤（最常用）
permissions	GitHub Actions 权限
runs-on	Runner 类型（默认 ubuntu-latest）
services	额外的服务容器（如数据库）
snapshot	环境快照配置
timeout-minutes	超时时间

常见问题

Q: 配置好后 Agent 还是找不到依赖怎么办？

A: 检查 job 名称是否精确为 copilot-setup-steps（区分大小写）。也可以手动触发 workflow（通过 workflow_dispatch）验证步骤是否执行成功。

Q: 能在 setup steps 里用 Docker 吗？

A: 可以，GitHub Actions 的 ubuntu-latest runner 已预装 Docker。配置服务容器（services）可以启动数据库等依赖服务。

Q: 这个配置文件会影响普通的 CI/CD workflow 吗？

A: 不会。copilot-setup-steps.yml 只有 copilot-setup-steps job 会被 Copilot 识别和使用，不影响仓库的其他 workflow。