Personalizando o ambiente de desenvolvimento para o GitHub Copilot, agente de codificação

Sobre a personalização do ambiente de desenvolvimento do agente de codificação Copilot

Ao trabalhar em uma tarefa, o Copilot tem acesso ao próprio ambiente de desenvolvimento efêmero, da plataforma GitHub Actions, em que pode explorar seu código, fazer alterações, executar testes automatizados e linters e muito mais.

Você pode personalizar o ambiente de desenvolvimento do Copilot com um arquivo de etapas de configuração do Copilot. Você pode usar um arquivo de etapas de instalação Copilot para:

•         [Pré-instalar as ferramentas ou as dependências no ambiente do Copilot}](#preinstalling-tools-or-dependencies-in-copilots-environment)
  

•           [Fazer o upgrade de executores do GitHub Actions} hospedados pelo GitHub} padrão para executores maiores](#upgrading-to-larger-github-hosted-github-actions-runners)
  

•           [Executar em executores auto-hospedados de GitHub Actions](#using-self-hosted-github-actions-runners)
  

•         [Fornecer o Copilot a um ambiente de desenvolvimento do Windows](#switching-copilot-to-a-windows-development-environment), no lugar do ambiente Ubuntu Linux padrão
  

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

Além disso, você pode:

•         [Definir variáveis de ambiente no ambiente do Copilot}](#setting-environment-variables-in-copilots-environment)
  

•         [Desabilitar ou personalizar o firewall do agente](/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent).
  

Personalizar o ambiente de desenvolvimento do Copilot com as etapas de configuração do Copilot

Você pode personalizar o ambiente do Copilot criando um arquivo de fluxo de trabalho especial do GitHub Actions, localizado em .github/workflows/copilot-setup-steps.yml no seu repositório.

Um arquivo copilot-setup-steps.yml se parece com um arquivo de fluxo de trabalho GitHub Actions, mas deve conter um só trabalho copilot-setup-steps. As etapas nesse trabalho serão executadas em GitHub Actions antes do Copilot começar a trabalhar. Para obter mais informações sobre arquivos de fluxo de trabalho GitHub Actions , consulte Sintaxe de fluxo de trabalho para o GitHub Actions.

Aqui está um exemplo simples de um arquivo copilot-setup-steps.yml para um projeto TypeScript que clona o projeto, instala Node.js e baixa e faz o cache das dependências do projeto. Você deve personalizar isso para se ajustar aos idiomas e dependências do seu próprio projeto.

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

No arquivo copilot-setup-steps.yml, você só pode personalizar as configurações a seguir do trabalho copilot-setup-steps. Se você tentar personalizar outras configurações, suas alterações serão ignoradas.

•         `steps` (consulte acima)
  

•         `permissions` (consulte acima)
  

•         `runs-on` (consulte abaixo)
  

• services
• snapshot

•         `timeout-minutes` (valor máximo: `59`)
  

Para obter mais informações sobre essas opções, consulte Sintaxe de fluxo de trabalho para o GitHub Actions.

Qualquer valor definido para a opção fetch-depth da ação actions/checkout será substituído para permitir que o agente reverta os commits mediante solicitação, mitigando os riscos de segurança. Para obter mais informações, consulte actions/checkout/README.md.

O arquivo copilot-setup-steps.yml será executado automaticamente como um fluxo de trabalho normal do GitHub Actions quando forem feitas alterações, para que você possa ver se ele é executado com êxito. Isso será exibido junto com outras verificações em uma pull request em que você cria ou modifica o arquivo.

Depois de ter mesclado o arquivo yml em sua ramificação padrão, você poderá executar manualmente o fluxo de trabalho na guia Ações do repositório a qualquer momento para verificar se tudo funciona como esperado. Para saber mais, confira Executar um fluxo de trabalho manualmente.

Quando o Copilot começa a trabalhar, as etapas de instalação são executadas e as atualizações são mostradas nos logs de sessão. Confira Acompanhamento das sessões do GitHub Copilot.

Se qualquer etapa de instalação falhar retornando um código de saída diferente de zero, o Copilot ignorará as etapas de configuração restantes e começará a trabalhar com o estado atual de seu ambiente de desenvolvimento.

Pré-instalando ferramentas ou dependências no ambiente do Copilot

Em seu ambiente de desenvolvimento efêmero, o Copilot pode criar ou compilar seu projeto e executar testes automatizados, linters e outras ferramentas. Para fazer isso, será necessário instalar as dependências do projeto.

O Copilot pode descobrir e instalar essas dependências por meio de um processo de avaliação e erro, mas isso pode ser lento e não confiável, considerando a natureza não determinística de LLMs (grandes modelos de linguagem) e, em alguns casos, pode ser completamente incapaz de baixar essas dependências, por exemplo, se elas forem privadas.

Você pode usar um arquivo de etapas de configuração do Copilot para instalar de forma determinística as ferramentas ou as dependências antes que o Copilot comece o trabalho. Para fazer isso, adicione steps ao trabalho 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

Fazer upgrade para executores do GitHub Actions hospedados pelo GitHub

Por padrão, Copilot funciona em um executor GitHub Actions padrão. Você pode atualizar para instâncias maiores para melhorar o desempenho (CPU e memória), obter mais espaço em disco e recursos avançados, como rede privada do Azure. Para obter mais informações, consulte Executores avançados.

1. Configure os executores maiores para sua organização. Para obter mais informações, consulte Gerenciar executores maiores.

2. Se você estiver usando executores maiores com a rede privada do Azure, configure sua rede privada do Azure para permitir o acesso de saída aos hosts necessários para o agente de codificação Copilot:

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

   •         `api.individual.githubcopilot.com` (se você espera que os usuários de Copilot Pro ou Copilot Pro+ usem agente de codificação Copilot no seu repositório)
     

   •         `api.business.githubcopilot.com` (se você espera que os usuários de Copilot Business usem o agente de codificação Copilot em seu repositório)
     

   •         `api.enterprise.githubcopilot.com` (se você espera que os usuários de Copilot Enterprise usem o agente de codificação Copilot em seu repositório)
     

   • Se você estiver usando o agente de terceiros OpenAI Codex (para obter mais informações, consulte Sobre agentes de terceiros):
     • npmjs.org
     • npmjs.com
     • registry.npmjs.com
     • registry.npmjs.org
     • skimdb.npmjs.com

3. Use um arquivo copilot-setup-steps.yml no seu repositório para configurar o agente de codificação Copilot para executar nos executores que você escolher. Defina a etapa runs-on do trabalho copilot-setup-steps para o rótulo e/ou grupo dos executores maiores que você deseja que o Copilot use. Para obter mais informações sobre como especificar corredores maiores com runs-on, consulte Como executar trabalhos em executores maiores.

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

Usar os executores de GitHub Actions auto-hospedados

Você pode executar o agente de codificação Copilot em executores auto-hospedados. Talvez você queira fazer isso para corresponder à forma como executa fluxos de trabalho de CI/CD em GitHub Actions, ou para fornecer ao Copilot acesso a recursos internos na sua rede.

Recomendamos que você use apenas o agente de codificação Copilot com executores temporários e de uso único, não reutilizáveis para múltiplos trabalhos. A maioria dos clientes configura isso usando o ARC (Controlador do Executor de Ações) ou o Cliente do Conjunto de Escala do Executor do GitHub Actions. Para saber mais, confira Referência de agentes autogeridos.

1. Configure os controles de segurança de rede para seus executores GitHub Actions para garantir que agente de codificação Copilot não tenha acesso aberto à sua rede ou à internet pública.

   Você deve configurar o firewall para permitir conexões com os hosts padrão necessários para os executores auto-hospedados do GitHub Actions}, além dos seguintes hosts:

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

   •         `api.individual.githubcopilot.com` (se você espera que os usuários de Copilot Pro ou Copilot Pro+ usem agente de codificação Copilot no seu repositório)
     

   •         `api.business.githubcopilot.com` (se você espera que os usuários de Copilot Business usem o agente de codificação Copilot em seu repositório)
     

   •         `api.enterprise.githubcopilot.com` (se você espera que os usuários de Copilot Enterprise usem o agente de codificação Copilot em seu repositório)
     

   • Se você estiver usando o agente de terceiros OpenAI Codex (para obter mais informações, consulte Sobre agentes de terceiros):
     • npmjs.org
     • npmjs.com
     • registry.npmjs.com
     • registry.npmjs.org
     • skimdb.npmjs.com

2. Desabilite o firewall integrado do agente de codificação Copilot nas configurações do repositório. O firewall não é compatível com executores auto-hospedados. A menos que isso esteja desabilitado, o uso do agente de codificação Copilot} será bloqueado. Para saber mais, confira Personalizando ou desabilitando o firewall para o agente de codificação do GitHub Copilot.

3. No arquivo copilot-setup-steps.yml, defina o atributo runs-on com o nome do seu conjunto de dimensionamento gerenciado pelo ARC:

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

4. Se você quiser configurar um servidor proxy para as conexões de agente de codificação Copilot com a Internet, configure as seguintes variáveis de ambiente conforme apropriado.

   Variable	Description	Example
   https_proxy	URL de proxy para tráfego HTTPS. Você pode incluir a autenticação básica, se necessário.	http://proxy.local http://192.168.1.1:8080 http://username:password@proxy.local
   http_proxy	URL de proxy para tráfego HTTP. Você pode incluir a autenticação básica, se necessário.	http://proxy.local http://192.168.1.1:8080 http://username:password@proxy.local
   no_proxy	Uma lista separada por vírgulas de hosts ou endereços IP que devem ignorar o proxy. Alguns clientes só respeitam endereços IP quando as conexões são feitas diretamente com o IP em vez de um nome de host.	example.com example.com,myserver.local:443,example.org

              | 
             `/path/to/key.pem`                               |
   

| node_extra_ca_certs | O caminho para o certificado SSL apresentado pelo servidor proxy. Você precisará configurar o necessário se o seu proxy interceptar conexões SSL. | /path/to/key.pem |

Você pode definir essas variáveis de ambiente seguindo as [instruções abaixo](#setting-environment-variables-in-copilots-environment) ou definindo-as diretamente no executor, por exemplo, com uma imagem de executor personalizada. Para obter mais informações sobre como criar uma imagem personalizada, consulte [AUTOTITLE](/actions/concepts/runners/actions-runner-controller#creating-your-own-runner-image).

Mudar o Copilot para um ambiente de desenvolvimento no sistema operacional Windows

Por padrão, o Copilot usa um ambiente de desenvolvimento baseado no Ubuntu Linux.

Talvez você queira usar um ambiente de desenvolvimento do Windows se estiver criando software para Windows ou se seu repositório usar uma cadeia de ferramentas baseada no Windows, para que Copilot possa criar seu projeto, executar testes e validar seu trabalho.

O firewall integrado do agente de codificação Copilot não é compatível com o Windows, portanto, recomendamos que você use apenas executores auto-hospedados ou maiores de GitHub com a rede privada do Azure, em que você pode implementar seus próprios controles de rede. Para obter mais informações sobre executores com rede privada do Azure, consulte Sobre a rede privada do Azure para executores hospedados no GitHub em sua empresa.

Para usar o Windows com executores auto-hospedados, siga as instruções na seção Usar os executores de GitHub Actions auto-hospedados acima, usando um rótulo para seus executores do Windows. Para usar o Windows com executores maiores hospedados por GitHub, siga as instruções na seção Atualizando para executores maiores acima, utilizando o rótulo adequado para os executores do Windows.

Ativando o Git Large File Storage (LFS)

Se você usar o Git LFS (Large File Storage) para armazenar arquivos grandes em seu repositório, precisará personalizar o ambiente do Copilot} para instalar o Git LFS e buscar objetos do LFS.

Para habilitar o Git LFS, adicione uma etapa actions/checkout ao trabalho copilot-setup-steps com a opção lfs definida como 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

Como definir variáveis de ambiente no ambiente do Copilot

Talvez você queira definir variáveis de ambiente no para configurar ou autenticar ferramentas ou dependências às quais ele tem acesso.

Para definir uma variável de ambiente para Copilot, crie uma variável ou segredo GitHub Actions no ambiente do copilot. Se o valor contiver informações confidenciais, por exemplo, uma senha ou chave de API, é melhor usar um segredo do GitHub Actions.

1. Em GitHub, acesse a página principal do repositório.

2. No nome do repositório, clique em Settings. Caso não consiga ver a guia "Configurações", selecione o menu suspenso , clique em Configurações.

   

3. Na barra lateral esquerda, clique em Ambientes.

4. Clique no ambiente copilot.

5. Para adicionar um segredo, em "Environment secrets", clique em Add environment secret. Para adicionar uma variável, em "Environment variables", clique em Add environment variable.

6. Preencha os campos "Name" e "Value" e clique em Add secret ou Add variable conforme apropriado.

Leitura adicional

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