自定义 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-cloud-agent)。

注意

组织所有者可以为其 Copilot云代理组织中的所有存储库配置默认运行程序类型，并选择是否允许存储库替代此默认值。有关详细信息，请参阅“为组织中的 GitHub Copilot 云代理配置运行器”。

自定义Copilot的开发环境，使用Copilot的设置步骤

可以通过创建位于Copilot存储库中的特殊GitHub Actions工作流文件来自定义.github/workflows/copilot-setup-steps.yml环境。

文件 copilot-setup-steps.yml 类似于普通 GitHub Actions 工作流文件，但必须包含单个 copilot-setup-steps 作业。会在GitHub Actions中执行此作业的步骤，然后在Copilot开始工作之前完成。有关工作流文件的详细信息 GitHub Actions ，请参阅 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 可以生成或编译项目并运行自动化测试、linters 和其他工具。为此，您需要安装项目的依赖项。

          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 运行器规模集客户端进行设置。有关详细信息，请参阅“自托管运行程序参考”。

注意

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

为 GitHub Actions 运行程序配置网络安全控制，以确保 Copilot云代理对网络或公共 Internet 没有开放访问权限。

必须将防火墙配置为允许连接到自托管运行器所需的 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`

          | 
       `ssl_cert_file`    |代理服务器提供的 SSL 证书的路径。 如果代理截获 SSL 连接，则需要对其进行配置。
        | 
       `/path/to/key.pem`                               |

| node_extra_ca_certs |代理服务器提供的 SSL 证书的路径。如果代理截获 SSL 连接，则需要对其进行配置。 | /path/to/key.pem |

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

将 Copilot 切换到 Windows 开发环境

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

如果要为Windows生成软件，或者存储库使用基于Windows的工具链，则可能需要使用Windows开发环境，以便Copilot可以生成项目、运行测试和验证其工作。

          Copilot云代理的集成防火墙不兼容于Windows，因此我们建议仅使用自托管运行程序或更大的GitHub托管运行程序，并且使用Azure专用网络，以便您实现自己的网络控制。 有关 Azure 专用网络中的运行器的详细信息，请参阅 [AUTOTITLE](/admin/configuring-settings/configuring-private-networking-for-hosted-compute-products/about-azure-private-networking-for-github-hosted-runners-in-your-enterprise)。

若要将Windows与自承载运行程序配合使用，请按照上述使用自承载GitHub Actions运行程序部分中的说明，使用Windows运行程序标签。若要将 Windows 与较大的 GitHub 托管运行程序配合使用，请按照上面的升级到更大的运行程序部分中的说明，使用 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环境变量，请在GitHub Actions环境中创建变量copilot或机密。如果值包含敏感信息（例如密码或 API 密钥），最好使用 GitHub Actions 机密。

在 GitHub 上，导航到存储库的主页面。
在仓库名称下，单击 “Settings”****。如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。
在左侧边栏中，单击“环境”。
单击 copilot 环境。
若要添加机密，请在“Environment secrets”下，单击“Add environment secret”。若要添加变量，请在“Environment variables”下，单击“Add environment variable”。
填写“Name”和“Value”字段，然后根据需要单击“Add secret”或“Add variable”********。

延伸阅读

        [AUTOTITLE](/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-firewall)

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

在本文中