自定义 GitHub Copilot 编码代理的开发环境

关于自定义 Copilot编程助理的开发环境

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

可以使用 Copilot 设置步骤文件自定义 Copilot 的开发环境。你可以使用 Copilot 设置步骤文件来：

        [在 Copilot 的环境中预安装工具或依赖项](#preinstalling-tools-or-dependencies-in-copilots-environment)

        [将标准的 GitHub 托管的 GitHub Actions 运行器升级到更大的运行器](#upgrading-to-larger-github-hosted-github-actions-runners)

        [在 GitHub Actions 自托管运行器上运行](#using-self-hosted-github-actions-runners)

        [为 Copilot 提供 Windows 开发环境](#switching-copilot-to-a-windows-development-environment)，而不是默认的 Ubuntu Linux 环境

        [启用 Git 大文件存储（LFS）](#enabling-git-large-file-storage-lfs)

此外，你可以：

        [在 Copilot 的环境中设置环境变量](#setting-environment-variables-in-copilots-environment)

        [禁用或自定义代理的防火墙](/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent)。

通过 Copilot 设置步骤自定义 Copilot 的开发环境

可以通过在存储库内的 .github/workflows/copilot-setup-steps.yml 位置创建一个特殊的 GitHub Actions 工作流文件来定制 Copilot 的环境。

          `copilot-setup-steps.yml` 文件看起来就像普通的 GitHub Actions 工作流文件，但必须包含单个 `copilot-setup-steps` 作业。 该作业中的步骤将在 GitHub Actions 中执行，并在 Copilot 开始工作之前完成。 有关GitHub Actions工作流文件的详细信息，请参阅[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions)。

注意

除非默认分支上存在 copilot-setup-steps.yml 工作流，否则不会触发该工作流。

下面是用于克隆project、安装 Node.js 并下载和缓存project依赖项的 TypeScript project copilot-setup-steps.yml 文件的简单示例。应对其进行自定义以适应自己的项目语言和依赖：

YAML

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:
      # ...

在 copilot-setup-steps.yml 文件中，只能自定义 copilot-setup-steps 作业的以下设置。如果尝试自定义其他设置，所做的更改将被忽略。

```
        `steps`（请参阅上文）
```

        `permissions`（请参阅上文）

```
        `runs-on`（请参阅下文）
```
services
snapshot

        `timeout-minutes`（最大值：`59`）

有关这些选项的详细信息，请参阅 GitHub Actions 的工作流语法。

为 fetch-depth 操作的 actions/checkout 选项设置的任何值都将被替代，以允许代理在请求时回滚提交，同时降低安全风险。有关详细信息，请参阅 actions/checkout/README.md。

          `copilot-setup-steps.yml` 文件在发生更改时会自动作为普通的 GitHub Actions 工作流运行，以便你查看是否运行成功。 在拉取请求中创建或修改该文件时，这项检查会与其他检查一起显示。

将 YAML 文件合并到默认分支后，您可以随时在仓库的 Actions 选项卡中手动运行该工作流，以确认一切运行正常。有关详细信息，请参阅“手动运行工作流”。

当 Copilot 开始工作时，将运行设置步骤，更新内容将显示在会话日志中。请参阅“跟踪GitHub Copilot 的会话”。

如果任何设置步骤返回非零退出代码而失败，Copilot 将跳过其余设置步骤，并根据开发环境的当前状态开始工作。

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

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

Copilot 可以通过试错过程自行发现并安装这些依赖项，但鉴于大型语言模型 (LLM) 的非确定性，这一过程可能既缓慢又不可靠。在某些情况下，可能完全无法下载这些依赖项，例如当这些依赖项属于专用依赖项时。

你可以使用 Copilot 设置步骤文件，在 Copilot 开始工作前以确定性的方式安装所需工具或依赖项。要做到这一点，请将 steps 添加到 copilot-setup-steps 任务：

# ...

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专用网络。有关详细信息，请参阅大型运行程序。

为你的组织设置更大型的运行器。有关详细信息，请参阅管理较大的运行器。

如果您在使用Azure专用网络的更大运行器，请将Azure专用网络配置为允许对所需主机的出站访问，以支持Copilot编程助理。

uploads.github.com
user-images.githubusercontent.com

        `api.individual.githubcopilot.com`（如果你预计 Copilot Pro 或 Copilot Pro+ 用户会在存储库中使用 Copilot编程助理）

        `api.business.githubcopilot.com`（如果你预计 Copilot业务 用户会在存储库中使用 Copilot编程助理）

        `api.enterprise.githubcopilot.com`（如果你预计 Copilot Enterprise 用户会在存储库中使用 Copilot编程助理）

如果您正在使用 OpenAI Codex 的第三方代理（有关详细信息，请参阅关于第三方代理）：
- npmjs.org
- npmjs.com
- registry.npmjs.com
- registry.npmjs.org
- skimdb.npmjs.com

使用存储库中的 copilot-setup-steps.yml 文件来配置 Copilot编程助理在你选择的运行器上运行。将 runs-on 作业中的 copilot-setup-steps 步骤设置为你希望 Copilot 使用的大型运行器的标签和/或组。有关使用 runs-on 指定更大的运行程序的详细信息，请参阅在较大的运行器上运行作业。
```
# ...

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

注意

Copilot编程助理仅兼容 Ubuntu x64 Linux 和 Windows 64 位运行器。不支持 macOS 或其他操作系统的运行器。

使用自托管的 GitHub Actions 运行器

你可以在自托管运行器上运行 Copilot编程助理。你可能希望这样做，以匹配您在 GitHub Actions 上运行 CI/CD 工作流的方式，或为 Copilot 提供对您网络上内部资源的访问权限。

我们建议仅将 Copilot编程助理与一次性、短生命周期的运行器配合使用，这些运行器不会被重复用于多个作业。大多数客户会使用 ARC（Actions Runner Controller）或 GitHub Actions Runner Scale Set Client 来进行此类配置。有关详细信息，请参阅“自托管运行程序参考”。

注意

Copilot编程助理仅兼容 Ubuntu x64 和 Windows 64 位运行器。不支持 macOS 或其他操作系统的运行器。

为 GitHub Actions 运行程序配置网络安全措施，以确保 Copilot编程助理没有对网络或公网开放访问。

您必须配置您的防火墙，以允许连接到用于 GitHub Actions 自托管运行器的标准主机，以及以下主机：
- uploads.github.com
- user-images.githubusercontent.com
- ```
        `api.individual.githubcopilot.com`（如果你预计 Copilot Pro 或 Copilot Pro+ 用户会在存储库中使用 Copilot编程助理）
```
- ```
        `api.business.githubcopilot.com`（如果你预计 Copilot业务 用户会在存储库中使用 Copilot编程助理）
```
- ```
        `api.enterprise.githubcopilot.com`（如果你预计 Copilot Enterprise 用户会在存储库中使用 Copilot编程助理）
```
- 如果您正在使用 OpenAI Codex 的第三方代理（有关详细信息，请参阅关于第三方代理）：
  - npmjs.org
  - npmjs.com
  - registry.npmjs.com
  - registry.npmjs.org
  - skimdb.npmjs.com
在存储库设置中禁用 Copilot编程助理的集成防火墙。防火墙与自托管运行器不兼容。在未禁用此功能的情况下，使用 Copilot编程助理将被阻止。有关详细信息，请参阅“为 GitHub Copilot 编码代理自定义或禁用防火墙”。
在你的copilot-setup-steps.yml文件中，将runs-on属性设置为 ARC 管理的伸缩集名称。
```
# ...

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

如果要为 Copilot编程助理的 Internet 连接配置代理服务器，请根据需要配置以下环境变量：

Variable	Description	Example
`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 地址而不是主机名时才接受 IP 地址。	`example.com` `example.com,myserver.local:443,example.org`

可以按照 [下面的说明](#setting-environment-variables-in-copilots-environment)设置这些环境变量，也可以直接在运行程序上设置它们，例如使用自定义运行程序映像。 有关生成自定义映像的详细信息，请参阅 [AUTOTITLE](/actions/concepts/runners/actions-runner-controller#creating-your-own-runner-image)。

将数据变量.product.prodname_copilot_short %} 切换为 Windows 开发环境

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

您可能希望使用 Windows 开发环境，如果您正在为 Windows 构建软件，或您的存储库使用基于 Windows 的工具链，Copilot 可以构建您的项目、运行测试并确认其工作成果。

Copilot编程助理的集成防火墙无法兼容 Windows。因此，我们建议您仅使用自承载运行程序或更大规模的 GitHub 托管运行程序，并结合 Azure 专用网络，在其中实现您自己的网络控制机制。有关Azure专用网络环境中的运行器的详细信息，请参阅关于企业中的 GitHub 托管的运行器的 Azure 专用网络。

若要将 Windows 与自承载运行器配合使用，请按照使用自承载 GitHub Actions 运行器部分中的说明进行操作，并使用 Windows 运行器标签。若要将 Windows 与较大的 GitHub托管的运行程序配合使用，请按照上面的 Upgrading 到更大的运行程序部分中的说明，使用 Windows 运行程序的标签。

启用 Git 大型文件存储（LFS）

如果使用 Git 大文件存储（LFS）将大型文件存储在存储库中，则您需要自定义 Copilot 的环境，以安装 Git LFS 并提取 LFS 对象。

要启用 Git LFS，请将 actions/checkout 步骤添加到 copilot-setup-steps 作业中，并将 lfs 选项设置为 true。

YAML

# ...

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 的环境中设置环境变量

你可能希望在 Copilot 的环境中设置环境变量，以配置或认证其可访问的工具或依赖项。

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

在 GitHub 上，导航到存储库的主页面。1. 在仓库名称下，单击 “Settings”****。如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。

1. 在左侧边栏中，单击“环境”。
单击 copilot 环境。
若要添加机密，请在“Environment secrets”下，单击“Add environment secret”。若要添加变量，请在“Environment variables”下，单击“Add environment variable”。
填写“Name”和“Value”字段，然后根据需要单击“Add secret”或“Add variable”********。

其他阅读材料

        [AUTOTITLE](/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent)

自定义 GitHub Copilot 编码代理的开发环境

在本文中