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

关于自定义 Copilot 编码智能体的开发环境

处理任务时，Copilot 可以访问其自己的临时开发环境（由 GitHub Actions 提供支持），可在其中浏览代码、进行更改、执行自动测试和 Linter 等。

可以自定义 Copilot 的环境，例如：

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

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

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

          [在基于 ARC 的 GitHub Actions 自托管运行器上运行](#using-self-hosted-github-actions-runners-with-arc)

          [启用 Git Large File Storage (LFS)](#enabling-git-large-file-storage-lfs)

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

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

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

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

可以改为在代理启动之前通过创建特殊的 GitHub Actions 工作流文件（位于存储库中的 .github/workflows/copilot-setup-steps.yml）来预先配置 Copilot 的环境。

copilot-setup-steps.yml 文件看起来就像普通的 GitHub Actions 工作流文件，但必须包含单个 copilot-setup-steps 作业。该作业将在 Copilot 开始工作之前在 GitHub Actions 中执行。有关 GitHub Actions 工作流文件的详细信息，请参阅“GitHub Actions 的工作流语法”。

注意

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

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

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

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

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

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

          `permissions`（请参阅上文）

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

services
snapshot

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

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

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

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

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

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

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

在 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”********。

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

默认情况下，Copilot 在资源有限的标准 GitHub Actions 运行器中工作。

可以选择改用具有更多高级功能的大型运行器，例如更多的 RAM、CPU 和磁盘空间，以及高级网络控制。如果发现性能不佳（例如在下载依赖项或运行测试时），则可能需要升级为大型运行器。有关详细信息，请参阅“大型运行器”。

必须先添加一个或多个大型运行器，并配置存储库以使用这些运行器，然后 Copilot 才可以使用更多大型运行器。请参阅“管理较大的运行器”。完成此操作后，可以使用 copilot-setup-steps.yml 文件告知 Copilot 使用大型运行器。

若要使用大型运行器，请将 copilot-setup-steps 作业的 runs-on 步骤设置为希望 Copilot 使用的大型运行器的标签和/或组。有关使用 runs-on 指定大型运行器的详细信息，请参阅“在较大的运行器上运行作业”。

# ...

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

注意

Copilot 编码智能体仅与 Ubuntu x64 Linux 运行器兼容。不支持使用 Windows、macOS 或其他操作系统的运行器。

通过 ARC 使用自承载 GitHub Actions 运行程序

可以在由 ARC（操作运行器控制器）提供支持的自托管运行器上运行 Copilot 编码智能体。必须先在环境中设置 ARC 托管的规模集。有关 ARC 的详细信息，请参阅 Actions Runner Controller。

警告

ARC 是唯一官方支持的自主托管 Copilot 编码智能体解决方案。出于安全原因，我们不建议将非 ARC 自托管运行器与 Copilot 编码智能体一起使用。

注意

Copilot 编码智能体仅与 Ubuntu x64 Linux 运行器兼容。不支持使用 Windows、macOS 或其他操作系统的运行器。

为 GitHub Actions 运行程序配置网络安全控制，以确保 Copilot 编码智能体不能开放访问您的网络或公共互联网。

您必须配置您的防火墙，以允许连接到用于 GitHub Actions 自托管运行器的标准主机，以及以下主机：
- api.githubcopilot.com
- uploads.github.com
- user-images.githubusercontent.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)。

启用 Git 大型文件存储 (LFS)

如果使用 Git Large File Storage (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

其他阅读材料

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

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

本文内容