Os runners auto-hospedados do GitHub Copilot permitem executar workflows na sua própria infraestrutura, em vez de usar os runners hospedados pelo GitHub. Essa configuração é essencial para empresas que precisam controlar custos, aplicar políticas de segurança ou acessar recursos de rede privada durante pipelines de CI/CD. Este artigo explica como registrar, configurar e gerenciar runners auto-hospedados para workflows do GitHub Copilot em um ambiente empresarial. Você aprenderá os pré-requisitos, etapas de instalação e armadilhas comuns a evitar.
Principais conclusões: Configuração de Runner Auto-hospedado para GitHub Copilot Enterprise
- Configurações da Empresa no GitHub > Actions > Runners: Adicione um novo runner no nível da empresa para disponibilizá-lo a todas as organizações e repositórios.
- Token de registro da interface do GitHub: Deve ser copiado e usado na máquina do runner durante o comando de configuração para autenticação.
- Atribuição a grupo de runners: Controle quais repositórios podem usar o runner atribuindo-o a um grupo específico com políticas de acesso definidas.
Por que usar Runners Auto-hospedados para Workflows do GitHub Copilot
Workflows do GitHub Copilot, como automação de revisão de código ou tarefas de ajuste fino de modelos, exigem recursos computacionais que podem ser executados por longos períodos. Runners auto-hospedados oferecem controle total sobre o sistema operacional, software instalado e conectividade de rede. Equipes empresariais os utilizam para acessar bancos de dados locais, registros de pacotes internos ou serviços protegidos por VPN que os runners hospedados pelo GitHub não conseguem alcançar. Você também evita a cobrança por minuto de tempo de computação, o que reduz custos para pipelines de alto volume.
Pré-requisitos para Configuração de Runner Auto-hospedado
Antes de começar, verifique estes requisitos:
- Uma conta GitHub Enterprise Cloud ou GitHub Enterprise Server com acesso de administrador às configurações da empresa.
- Uma máquina com sistema operacional suportado: Ubuntu 20.04 ou superior, Windows Server 2019 ou superior, ou macOS 11 ou superior.
- Mínimo de 2 vCPUs, 8 GB de RAM e 50 GB de espaço livre em disco para workflows relacionados ao Copilot.
- Acesso HTTPS de saída para api.github.com ou o hostname do GitHub Enterprise Server.
- Git instalado na máquina do runner (versão 2.30 ou superior).
Passos para Adicionar um Runner Auto-hospedado no Nível da Empresa
Estas instruções cobrem a adição de um runner que todas as organizações da sua empresa podem usar. Se precisar de isolamento de runner por organização, repita o processo no nível da organização.
- Navegue até as configurações de runner da empresa
Faça login no GitHub.com. No canto superior direito, clique na sua foto de perfil e selecione Suas empresas. Clique no nome da empresa. Na barra lateral esquerda, clique em Settings, depois Actions e depois Runners. - Clique em Add runner
Na página Runners, clique no botão verde Add runner. Uma janela modal aparece com instruções para o sistema operacional selecionado. - Escolha o SO da máquina do runner
Na janela modal, selecione o sistema operacional que corresponde à sua máquina runner. O GitHub fornece links de download para o binário do agente runner e o script de configuração específico para aquele SO. - Baixe e extraia o agente runner
Na máquina runner, abra um terminal ou PowerShell como administrador. Execute o comando de download mostrado na janela modal. Para Linux, o comando é assim:curl -o actions-runner-linux-x64-2.317.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.317.0/actions-runner-linux-x64-2.317.0.tar.gz
Extraia o arquivo:tar xzf actions-runner-linux-x64-2.317.0.tar.gz - Execute o comando de configuração com o token de registro
Copie o comando de configuração da janela modal do GitHub. Ele inclui um token de registro único. Execute-o na máquina runner. Exemplo para Linux:./config.sh --url https://github.com/enterprises/SUA_EMPRESA --token ABC123DEF456
Quando solicitado, insira o nome do runner, labels e pasta de trabalho. Para workflows do Copilot, adicione um label personalizado comocopilot-runnerpara direcioná-lo especificamente. - Inicie o serviço do runner
Após a configuração, execute o comando de instalação do serviço. No Linux:sudo ./svc.sh install
Depois inicie o serviço:sudo ./svc.sh start
No Windows, use os comandos PowerShell fornecidos para instalação do serviço. - Verifique se o runner aparece no GitHub
Atualize a página Runners no GitHub. O novo runner deve aparecer com um indicador de status verde. Clique no nome do runner para ver seus labels, endereço IP e timestamp da última atividade.
Grupos de Runners e Controle de Acesso
Grupos de runners permitem restringir quais repositórios ou organizações podem usar um runner auto-hospedado específico. Por padrão, um novo runner é colocado no grupo Default, que permite que todas as organizações da empresa o utilizem. Para criar um grupo restrito:
- Vá para Runner groups
Nas configurações da empresa, em Actions, clique em Runner groups. - Crie um novo grupo
Clique em New group. Digite um nome comoCopilot-Only. - Selecione o acesso das organizações
Escolha Selected organizations e marque as organizações que devem ter acesso. Clique em Save. - Mova o runner para o novo grupo
Volte para a página Runners. Clique no nome do runner, depois em Settings. No menu suspenso Runner group, selecione o novo grupo e clique em Save.
Problemas Comuns e Suas Soluções
Runner aparece offline após o registro
O serviço do agente runner pode não estar em execução. Verifique o status do serviço com sudo ./svc.sh status no Linux ou Get-Service -Name actions.runner. no Windows. Se estiver parado, inicie o serviço. Verifique também se a máquina runner tem acesso HTTPS de saída para api.github.com. Regras de firewall ou configurações de proxy podem bloquear a conexão.
Jobs do workflow ficam pendentes aguardando um runner
Provavelmente o arquivo YAML do workflow não especifica o label runs-on correto. Verifique os labels do runner no GitHub. Atualize o arquivo de workflow para corresponder. Exemplo:runs-on: [self-hosted, copilot-runner]
Se o grupo de runners restringe o acesso, confirme que o repositório está em uma organização permitida.
Agente runner falha ao iniciar após atualização do SO
Bibliotecas do sistema ou dependências podem ter mudado. Desinstale o serviço do runner, exclua a pasta _work e execute novamente as etapas de configuração e instalação do serviço. O binário do agente runner permanece compatível com atualizações menores do SO, mas atualizações de versão principal exigem uma nova configuração.
| Item | Runner Hospedado pelo GitHub | Runner Auto-hospedado |
|---|---|---|
| Descrição | VM efêmera gerenciada pelo GitHub | Máquina persistente gerenciada pela sua equipe |
| Modelo de custo | Cobrança por minuto de computação | Sem cobrança por minuto; você paga pela infraestrutura |
| Acesso à rede | Apenas internet pública | Rede privada, VPN, recursos locais |
| Software personalizado | Limitado a ferramentas pré-instaladas | Qualquer software que você instalar |
| Escolha do SO | Versões de Ubuntu, Windows, macOS selecionadas pelo GitHub | Qualquer versão de SO que você escolher e mantiver |
| Tempo limite do job | 6 horas por job | Sem tempo limite imposto; defina o seu próprio |
Runners auto-hospedados dão às empresas controle total sobre o ambiente de CI/CD para workflows do Copilot. Após a configuração, você pode direcionar labels específicos de runner nos arquivos YAML do workflow para rotear jobs para a máquina correta. Para grandes frotas, considere usar o GitHub Actions Runner Controller para Kubernetes para escalar runners automaticamente com base na profundidade da fila.