为 GitHub Copilot 云代理定制开发环境

关于定制 Copilot 云代理的开发环境

在完成任务时，Copilot 可以访问由 GitHub Actions 提供支持的临时开发环境，在该环境中它可以浏览您的代码、进行更改、执行自动化测试和代码检查等操作。

You can customize Copilot's development environment with a Copilot 设置步骤文件. You can use a Copilot setup steps file to

• 在 Copilot 环境中预装工具或依赖项
• 从标准的 GitHub 托管的 GitHub Actions 运行器升级到更大的运行器
• 在 GitHub Actions 自托管运行器上运行
• 为 Copilot 提供 Windows 开发环境，而非默认的 Ubuntu Linux 环境
• 启用 Git 大文件存储 (LFS)

此外，您还可以

• 在 Copilot 环境中设置环境变量
• 禁用或自定义代理的防火墙.

使用 Copilot 设置步骤定制 Copilot 的开发环境

You can customize Copilot's environment by creating a special GitHub Actions workflow file, located at .github/workflows/copilot-setup-steps.yml within your repository.

A copilot-setup-steps.yml file looks like a normal GitHub Actions workflow file, but must contain a single copilot-setup-steps job. The steps in this job will be executed in GitHub Actions before Copilot starts working. For more information on GitHub Actions workflow files, see GitHub Actions 的工作流语法.

下面是一个针对 TypeScript 项目的 copilot-setup-steps.yml 简单示例，该示例会克隆项目、安装 Node.js 并下载和缓存项目的依赖项。您应根据自己的项目语言和依赖项进行自定义。

name: "Copilot Setup Steps"

# Automatically run the setup steps when they are changed to allow for easy validation, and
# allow manual testing through the repository's "Actions" tab
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
  copilot-setup-steps:
    runs-on: ubuntu-latest

    # Set the permissions to the lowest permissions possible needed for your steps.
    # Copilot will be given its own token for its operations.
    permissions:
      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission.
      # If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
      contents: read

    # You can define any steps you want, and they will run before the agent starts.
    # If you do not check out your code, Copilot will do this for you.
    steps:
      # ...

name: "Copilot Setup Steps"

# Automatically run the setup steps when they are changed to allow for easy validation, and
# allow manual testing through the repository's "Actions" tab
on:
  workflow_dispatch:
  push:
    paths:
      - .github/workflows/copilot-setup-steps.yml
  pull_request:
    paths:
      - .github/workflows/copilot-setup-steps.yml

jobs:
  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
  copilot-setup-steps:
    runs-on: ubuntu-latest

    # Set the permissions to the lowest permissions possible needed for your steps.
    # Copilot will be given its own token for its operations.
    permissions:
      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission.
      # If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
      contents: read

    # You can define any steps you want, and they will run before the agent starts.
    # If you do not check out your code, Copilot will do this for you.
    steps:
      # ...

In your copilot-setup-steps.yml file, you can only customize the following settings of the copilot-setup-steps job. If you try to customize other settings, your changes will be ignored.

• steps（见上文）
• permissions（见上文）
• runs-on（见下文）
• services
• 快照
• timeout-minutes（最大值：59）

For more information on these options, see GitHub Actions 的工作流语法.

Any value that is set for the fetch-depth option of the actions/checkout action will be overridden to allow the agent to rollback commits upon request, while mitigating security risks. For more information, see actions/checkout/README.md.

当对 copilot-setup-steps.yml 文件进行更改时，它会自动作为普通的 GitHub Actions 工作流运行，以便您查看是否成功执行。此工作流会在您创建或修改文件的拉取请求中与其他检查一起显示。

将该 yml 文件合并到默认分支后，您可以随时在仓库的 Actions（操作）选项卡中手动运行工作流，以检查一切是否如预期般工作。更多信息请参阅 手动运行工作流。

Copilot 开始工作时，会运行您的设置步骤，并在会话日志中显示更新。请参阅 追踪 GitHub Copilot 会话。

If any setup step fails by returning a non-zero exit code, Copilot will skip the remaining setup steps and begin working with the current state of its development environment.

在 Copilot 环境中预装工具或依赖项

在其临时开发环境中，Copilot 可以构建或编译您的项目并运行自动化测试、代码检查等工具。为此，它需要安装项目的依赖项。

Copilot 可以通过反复试验自行发现并安装这些依赖项，但由于大语言模型（LLM）的非确定性，这可能既慢又不可靠，在某些情况下甚至根本无法下载这些依赖项——例如，它们是私有的。

You can use a Copilot setup steps file to deterministically install tools or dependencies before Copilot starts work. To do this, add steps to the copilot-setup-steps job

# ...

jobs:
  copilot-setup-steps:
    # ...

    # You can define any steps you want, and they will run before the agent starts.
    # If you do not check out your code, Copilot will do this for you.
    steps:
      - name: Checkout code
        uses: actions/checkout@v5

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

      - name: Install JavaScript dependencies
        run: npm ci

升级到更大的 GitHub 托管的 GitHub Actions 运行器

默认情况下，Copilot 在标准的 GitHub Actions 运行器上运行。您可以升级到更大的运行器，以获得更好的性能（CPU 与内存）、更多磁盘空间以及 Azure 私有网络等高级功能。更多信息请参阅 更大的运行器。

1. Set up larger runners for your organization. For more information, see 管理更大的运行器.

2. If you are using larger runners with Azure private networking, configure your Azure private network to allow outbound access to the hosts required for Copilot cloud agent

   • uploads.github.com
   • user-images.githubusercontent.com
   • api.individual.githubcopilot.com（如果您预计 Copilot Pro 或 Copilot Pro+ 用户将在您的仓库中使用 Copilot 云代理）
   • api.business.githubcopilot.com（如果您预计 Copilot Business 用户将在您的仓库中使用 Copilot 云代理）
   • api.enterprise.githubcopilot.com（如果您预计 Copilot Enterprise 用户将在您的仓库中使用 Copilot 云代理）
   • If you are using the OpenAI Codex third-party agent (for more information, see About third-party agents)
     • npmjs.org
     • npmjs.com
     • registry.npmjs.com
     • registry.npmjs.org
     • skimdb.npmjs.com

3. Use a copilot-setup-steps.yml file in your repository to configure Copilot cloud agent to run on your chosen runners. Set the runs-on step of the copilot-setup-steps job to the label and/or group for the larger runners you want Copilot to use. For more information on specifying larger runners with runs-on, see Running jobs on larger runners.

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

使用自托管的 GitHub Actions 运行器

You can run Copilot cloud agent on self-hosted runners. You may want to do this to match how you run CI/CD workflows on GitHub Actions, or to give Copilot access to internal resources on your network.

We recommend that you only use Copilot cloud agent with ephemeral, single-use runners that are not reused for multiple jobs. Most customers set this up using ARC (Actions Runner Controller) or the GitHub Actions Runner Scale Set Client. For more information, see Self-hosted runners reference.

1. Configure network security controls for your GitHub Actions runners to ensure that Copilot cloud agent does not have open access to your network or the public internet.

   You must configure your firewall to allow connections to the GitHub Actions 自托管运行器所需的标准主机, plus the following hosts

   • uploads.github.com
   • user-images.githubusercontent.com
   • api.individual.githubcopilot.com（如果您预计 Copilot Pro 或 Copilot Pro+ 用户将在您的仓库中使用 Copilot 云代理）
   • api.business.githubcopilot.com（如果您预计 Copilot Business 用户将在您的仓库中使用 Copilot 云代理）
   • api.enterprise.githubcopilot.com（如果您预计 Copilot Enterprise 用户将在您的仓库中使用 Copilot 云代理）
   • If you are using the OpenAI Codex third-party agent (for more information, see About third-party agents)
     • npmjs.org
     • npmjs.com
     • registry.npmjs.com
     • registry.npmjs.org
     • skimdb.npmjs.com

2. Disable Copilot cloud agent's integrated firewall in your repository settings. The firewall is not compatible with self-hosted runners. Unless this is disabled, use of Copilot cloud agent will be blocked. For more information, see 自定义或禁用 GitHub Copilot 云代理的防火墙.

3. In your copilot-setup-steps.yml file, set the runs-on attribute to your ARC-managed scale set name

   # ...
   
   jobs:
     copilot-setup-steps:
       runs-on: arc-scale-set-name
       # ...
   

4. If you want to configure a proxy server for Copilot cloud agent's connections to the internet, configure the following environment variables as appropriate

   变量	描述	示例
   https_proxy	HTTPS 流量的代理 URL。如有需要，可包含基本身份验证。	http://proxy.local http://192.168.1.1:8080 http://username:password@proxy.local
   http_proxy	HTTP 流量的代理 URL。如有需要，可包含基本身份验证。	http://proxy.local http://192.168.1.1:8080 http://username:password@proxy.local
   no_proxy	一个以逗号分隔的主机或 IP 地址列表，这些地址应绕过代理。某些客户端仅在直接使用 IP 而非主机名进行连接时才会识别 IP 地址。	example.com example.com,myserver.local:443,example.org
   ssl_cert_file	您代理服务器提供的 SSL 证书的路径。如果您的代理拦截 SSL 连接，则需要配置此项。	/path/to/key.pem
   node_extra_ca_certs	您代理服务器提供的 SSL 证书的路径。如果您的代理拦截 SSL 连接，则需要配置此项。	/path/to/key.pem

   You can set these environment variables by following the 在 Copilot 环境中设置环境变量 instructions below, or by setting them on the runner directly, for example with a custom runner image. For more information on building a custom image, see Actions Runner Controller.

切换 Copilot 到 Windows 开发环境

默认情况下，Copilot 使用基于 Ubuntu Linux 的开发环境。

You may want to use a Windows development environment if you're building software for Windows or your repository uses a Windows-based toolchain so Copilot can build your project, run tests and validate its work.

Copilot 云代理的集成防火墙与 Windows 不兼容，因此我们建议仅在自托管运行器或带有 Azure 私有网络的更大 GitHub 托管运行器上使用，以便您自行实现网络控制。有关 Azure 私有网络运行器的更多信息，请参阅 关于企业中 GitHub 托管运行器的 Azure 私有网络。

若要在自托管运行器上使用 Windows，请遵循上文 使用自托管 GitHub Actions 运行器 部分的说明，并使用 Windows 运行器的标签。若要在更大的 GitHub 托管运行器上使用 Windows，请遵循上文 升级到更大运行器 部分的说明，并使用 Windows 运行器的标签。

启用 Git 大文件存储 (LFS)

If you use Git Large File Storage (LFS) to store large files in your repository, you will need to customize Copilot's environment to install Git LFS and fetch LFS objects.

To enable Git LFS, add a actions/checkout step to your copilot-setup-steps job with the lfs option set to true.

# ...

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read # for actions/checkout
    steps:
      - uses: actions/checkout@v5
        with:
          lfs: true

# ...

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read # for actions/checkout
    steps:
      - uses: actions/checkout@v5
        with:
          lfs: true

在 Copilot 环境中设置环境变量

You may want to set environment variables in Copilot's environment to configure or authenticate tools or dependencies that it has access to.

要为 Copilot 设置环境变量，请在 copilot 环境中创建 GitHub Actions 变量或密钥。如果值包含敏感信息，例如密码或 API 密钥，建议使用 GitHub Actions 密钥。

1. 在 GitHub 上，导航至仓库的主页面。

2. 在您的仓库名称下，点击 Settings（设置）。如果看不到 “Settings（设置）” 选项卡，请选择 More（更多） 下拉菜单，然后点击 Settings（设置）。

   

3. 在左侧边栏，点击 环境。

4. Click the copilot environment.

5. To add a secret, under "Environment secrets," click Add environment secret. To add a variable, under "Environment variables," click Add environment variable.

6. Fill in the "Name" and "Value" fields, and then click Add secret or Add variable as appropriate.

延伸阅读

• 自定义或禁用 GitHub Copilot 云代理的防火墙