Referência de executores auto-hospedados

Encontre informações sobre como configurar e usar executores auto-hospedados.

Neste artigo

Requisitos para executores auto-hospedados

Você pode usar um computador como um executor auto-hospedado, desde que ele atenda a estes requisitos:

  • Você pode instalar e executar o aplicativo do executor auto-hospedado na máquina. Confira Sistemas operacionais com suporte e Arquiteturas de processador com suporte.
  • A máquina pode comunicar-se com GitHub Actions.
  • A máquina tem recursos de hardware suficientes para o tipo de fluxos de trabalho que você planeja executar. O aplicativo de runner autogerenciado requer apenas recursos mínimos.
  • Se você desejar executar fluxos de trabalho que usam ações do contêiner do Docker ou dos contêineres de serviço, você deverá usar uma máquina Linux e o Docker deve estar instalados.

Sistemas operacionais compatíveis

Linux

  • Red Hat Enterprise Linux 8 ou posterior
  • CentOS 8 ou posterior
  • Oracle Linux 8 ou posterior
  • Fedora 29 ou versão posterior
  • Debian 10 ou versão posterior
  • Ubuntu 20.04 ou posterior
  • Linux Mint 20 ou posterior
  • openSUSE 15.2 ou posterior
  • SUSE Enterprise Linux (SLES) 15 SP2 ou posterior

Windows

  • Windows 10 64 bits
  • Windows 11 de 64 bits
  • Windows Server 2016 de 64 bits
  • Windows Server 2019 de 64 bits
  • Windows Server 2022 de 64 bits

macOS

  • macOS 11.0 (Big Sur) ou posterior

Arquiteturas de processador com suporte

  •         `x64` – Linux, macOS e Windows.

  •           `ARM64` – Linux, macOS, Windows (atualmente em versão prévia pública).

  •         `ARM32` – Linux.

Precedência de encaminhamento para executores auto-hospedados

Ao encaminhar um trabalho para um executor auto-hospedado, o GitHub procura um executor que corresponde aos rótulos runs-on do trabalho e grupos:

  • Se o GitHub encontrar um executor online e ocioso que corresponda aos rótulos runs-on do trabalho e grupos, o trabalho será atribuído e enviado ao executor.
    • Se o executor não pegar a tarefa atribuída dentro de 60 segundos, a tarefa será enfileirada novamente para que um novo executor possa aceitá-la.
  • Se o GitHub não encontrar um executor online e ocioso que corresponda aos rótulos runs-on do trabalho e grupos, o trabalho permanecerá na fila até que um executor fique online.
  • Se o trabalho permanecer na fila por mais de 24 horas, o trabalho falhará.

Dimensionamento automático

O dimensionamento automático permite ajustar dinamicamente o número de executores auto-hospedados com base na demanda. Isso ajuda a otimizar a utilização de recursos e garante capacidade de executor suficiente durante os horários de pico, reduzindo os custos durante períodos de baixa atividade. Há várias abordagens para implementar o dimensionamento automático para corredores auto-hospedados, cada uma com diferentes compensações em termos de complexidade, confiabilidade e capacidade de resposta.

Actions Runner Controller

GitHub-executores hospedados inerentemente escalonam automaticamente com base em suas necessidades. GitHub-hosted executores podem ser uma alternativa econômica e de baixa manutenção ao desenvolvimento ou implementação de soluções de dimensionamento automático. Para saber mais, confira Executores hospedados no GitHub.

Actions Runner Controller (ARC) é a implementação de referência das APIs de conjunto de dimensionamento do GitHub e a solução recomendada baseada em Kubernetes para o escalonamento automático de executores auto-hospedados. O ARC fornece uma solução completa de dimensionamento automático pronta para uso em produção para equipes que executam GitHub Actions em ambientes Kubernetes.

GitHub recomenda o ARC para organizações com infraestrutura do Kubernetes e equipes com experiência no Kubernetes. O ARC gerencia todo o ciclo de vida dos executores em seu cluster, desde o provisionamento até a execução do trabalho, passando pela limpeza.

Para saber mais, confira Controlador de Ações Runner e Suporte para o Controlador do Executor de Ações.

GitHub Actions Cliente de Conjunto de Escalonamento de Executor

O GitHub Actions Runner Scale Set Client é um módulo autônomo baseado em Go que capacita equipes de plataforma, integradores e provedores de infraestrutura a criar soluções personalizadas de dimensionamento automático para GitHub Actions executores em VMs, contêineres, infraestrutura local e serviços de nuvem, com suporte para plataformas Windows, Linux e macOS.

O cliente orquestra as interações de API do GitHub para escalabilidade, deixando o provisionamento de infraestrutura para você. Você define como os executores são criados, dimensionados e destruídos e configura os executores com vários rótulos para roteamento e direcionamento de trabalho flexíveis. Isso oferece às organizações um controle mais detalhado sobre o gerenciamento do ciclo de vida dos runners e fornece telemetria em tempo real para a execução das tarefas.

O cliente foi projetado para trabalhar fora da caixa com configurações básicas, permitindo que as equipes implementem rapidamente o dimensionamento automático. No entanto, seu verdadeiro poder está em sua flexibilidade: o cliente é criado para ser estendido e personalizado para atender aos requisitos de infraestrutura, restrições de conformidade e fluxos de trabalho operacionais específicos de cada organização. Se você precisar de lógica de dimensionamento simples ou estratégias complexas de provisionamento de vários ambientes, o cliente se adaptará às suas necessidades.

O GitHub Actions Runner Scale Set Client é um projeto de software livre. O repositório actions/scaleset contém o código-fonte completo, documentação abrangente e exemplos práticos para ajudá-lo a começar. Você encontrará guias de implementação, configurações de exemplo para vários cenários de infraestrutura e arquiteturas de referência que demonstram como integrar o cliente a diferentes sistemas de provisionamento. O repositório também inclui diretrizes de contribuição para equipes interessadas em estender o cliente ou compartilhar seus padrões de dimensionamento automático com a comunidade.

          **Observação:** o Cliente de Conjunto de Escalonamento do Executor não é um substituto para Actions Runner Controller (ARC), que continua sendo a implementação de referência das APIs do conjunto de escalonamento e a solução recomendada no Kubernetes para escalonamento automático de executores. Em vez disso, o cliente é uma ferramenta complementar para interface com as mesmas APIs de conjunto de escalas para criar soluções de escalonamento automático personalizadas fora do Kubernetes.

Executores efêmeros para dimensionamento automático

GitHub recomenda implementar o dimensionamento automático com executores auto-hospedados efêmeros. Nãose recomenda o dimensionamento automático com executores auto-hospedados persistentes. Em certos casos, GitHub não pode garantir que os trabalhos não sejam atribuídos a executores persistentes enquanto eles são desativados. Com executores efêmeros, é possível garantir isso, porque GitHub só atribui um trabalho a um executor.

Esta abordagem permite que você gerencie os seus executores como sistemas efêmeros, já que você pode usar automação para fornecer um ambiente limpo para cada trabalho. Isso ajuda a limitar a exposição de quaisquer recursos sensíveis de trabalhos anteriores e também ajuda a mitigar o risco de um runner comprometido receber novos trabalhos.

Aviso

Os arquivos de log do aplicativo do executor para executores efêmeros devem ser encaminhados para uma solução de armazenamento de logs externo para fins de solução de problemas e diagnóstico. Embora não seja necessária a implantação dos executores efêmeros, o GitHub recomenda garantir que os logs do executor sejam encaminhados e preservados externamente antes de implantar uma solução de dimensionamento automático de executores efêmeros em um ambiente de produção. Para saber mais, confira Monitorar e solucionar problemas de executores auto-hospedados.

Para adicionar um executor efêmero ao seu ambiente, inclua o parâmetro --ephemeral ao registrar o executor usando config.sh. Por exemplo:

./config.sh --url https://github.com/octo-org --token example-token --ephemeral

O serviço GitHub Actions irá desregistrar automaticamente o runner após ele ter processado um único trabalho. Em seguida, você poderá criar a sua própria automação que limpa o runner depois que ele tiver seu registro cancelado.

Observação

Se um trabalho estiver rotulado para certo tipo de executor, mas nenhuma correspondência desse tipo estiver disponível, o trabalho não falhará imediatamente no momento da colocação na fila. Em vez disso, o trabalho permanecerá na fila até que o período de tempo limite de 24 horas expire.

Como alternativa, você pode criar executores just-in-time efêmeros usando a API REST. Para saber mais, confira Pontos de extremidade da API REST para executores auto-hospedados.

Atualizações de software dos executores em executores auto-hospedados

Por padrão, os executores auto-hospedados realizarão automaticamente uma atualização de software sempre que uma nova versão do executor estiver disponível. Se você usar executores efêmeros em contêineres, isso pode levar a atualizações de software repetidas quando uma nova versão do executor for lançada. A desabilitação das atualizações automáticas permite que você atualize a versão do executor na imagem do contêiner diretamente no seu próprio agendamento.

Para desativar as atualizações automáticas de software e instalar atualizações de software por conta própria, especifique o sinalizador --disableupdate ao registrar o executor usando config.sh. Por exemplo:

./config.sh --url https://github.com/YOUR-ORGANIZATION --token EXAMPLE-TOKEN --disableupdate

Se você desabilitar as atualizações automáticas, ainda deverá atualizar a versão do seu executor regularmente. A nova funcionalidade do GitHub Actions exige alterações no serviço do GitHub Actions e no software do executor. O executor pode não conseguir processar corretamente os trabalhos que aproveitam novas funcionalidades em GitHub Actions sem a atualização de um software.

Se você desabilitar as atualizações automáticas, será necessário atualizar a versão do seu executor no prazo de 30 dias a contar da nova versão disponível. Você pode querer se inscrever para receber notificações de lançamentos no repositório actions/runner. Para saber mais, confira Configurar notificações.

Para obter instruções sobre como instalar a última versão do executor, confira as instruções de instalação da última versão.

Aviso

Todas as atualizações lançadas para o software, incluindo versões principais, secundárias ou de patch, são consideradas como uma atualização disponível. Se você não executar uma atualização de software em 30 dias, o serviço do GitHub Actions não colocará trabalhos na fila para o seu executor. Além disso, se uma atualização crítica de segurança for necessária, o serviço de GitHub Actions não colocará os trabalhos na fila do seu executor até que ele seja atualizado.

Webhooks para dimensionamento automático

Você pode criar seu ambiente de dimensionamento automático usando cargas recebidas do webhook workflow_job. Esse webhook está disponível nos níveis de repositório, organização e empresa, e a carga útil desse evento contém uma chave action que corresponde às fases do ciclo de vida de uma tarefa de workflow; por exemplo, quando as tarefas são queued, in_progress e completed. Você deverá criar a sua própria automação de dimensionamento em resposta a estas cargas de webhook.

          **Nota:** Essa abordagem depende da pontualidade da entrega de webhook para tomar decisões de dimensionamento, o que pode introduzir atrasos e preocupações de confiabilidade. Considere usar o Actions Controller ou o Scale Set Client para cenários de escalonamento automático de grande volume.

Requisitos de autenticação

Você pode registrar e excluir os executores auto-hospedados do repositório e da organização usando a API. Para efetuar a autenticação na API, a implementação do seu dimensionamento automático pode usar um token de acesso ou um aplicativo de GitHub.

Seu token de acesso exigirá o seguinte escopo:

  • Para repositórios privados, use um token de acesso com o escopo indicado por repo.
  • Para repositórios públicos, use um token de acesso com o public_repo escopo.
  • Para organizações, use um token de acesso que possua o escopo admin:org.

Para efetuar a autenticação usando um aplicativo de GitHub, este deverá ter as seguintes permissões:

  • Para repositórios, atribua a permissão administration.
  • Para organizações, atribua a permissão organization_self_hosted_runners.

Você pode registrar e excluir os executores auto-hospedados da empresa usando a API. Para efetuar a autenticação na API, sua implementação de dimensionamento automático pode usar um token de acesso.

Seu token de acesso exigirá o escopo manage_runners:enterprise.

Comunicação

Executores auto-hospedados se conectam ao GitHub para receber atribuições de trabalho e baixar novas versões do aplicativo executor.

O aplicativo de executor do GitHub Actions tem código aberto. Você pode contribuir e apresentar problemas no repositório do executor. Quando uma nova versão é lançada, o aplicativo do executor atualiza-se automaticamente quando uma tarefa é atribuída ao executor, ou dentro de uma semana após a liberação, caso o executor não tenha recebido nenhum trabalho.

Requisitos de comunicação com GitHub

  • O aplicativo do executor auto-hospedado deve estar em execução no computador host para aceitar e executar trabalhos do GitHub Actions.
  • O computador host deve ter acesso à rede apropriado com pelo menos 70 Kbps de velocidade de upload e download.
  • O computador host deve ser capaz de fazer conexões HTTPS de saída pela porta 443.
  • Dependendo da função dos fluxos de trabalho atribuídos ao seu executor auto-hospedado, o computador host deve ser capaz de se comunicar com os domínios do GitHub listados abaixo.

Domínios acessíveis por função

Observação

Alguns dos domínios listados são configurados por meio de registros CNAME. Alguns firewalls podem exigir que você adicione regras de maneira recursiva para todos os registros CNAME. Observe que os registros CNAME poderão mudar no futuro e que apenas os domínios listados permanecerão constantes.

Necessário para operações essenciais:

Shell
github.com
api.github.com
*.actions.githubusercontent.com

          **Necessário para baixar as ações:**
Shell
codeload.github.com

          **Necessário para upload/download de caches e artefatos de fluxo de trabalho:**
Shell
results-receiver.actions.githubusercontent.com
*.blob.core.windows.net

          **Necessário para as atualizações de versão do executor:**
Shell
objects.githubusercontent.com
objects-origin.githubusercontent.com
github-releases.githubusercontent.com
github-registry-files.githubusercontent.com

          **Necessário para recuperar tokens OIDC:**
Shell
*.actions.githubusercontent.com

          **Necessário para baixar ou publicar pacotes ou contêineres em pacotes do GitHub:**
Shell
*.pkg.github.com
pkg-containers.githubusercontent.com
ghcr.io

          **Necessário para o Git Large File Storage**
Shell
github-cloud.githubusercontent.com
github-cloud.s3.amazonaws.com

Necessário para trabalhos das Dependabot updates

Shell
dependabot-actions.githubapp.com

          **Necessário para baixar ativos da versão:**
Shell
release-assets.githubusercontent.com

          **Necessário para a VNet:**
Shell
api.snapcraft.io

Além disso, seu fluxo de trabalho pode exigir acesso a outros recursos de rede.

Se você usar uma lista de endereços IP permitida para a sua a sua organização ou conta corporativa do GitHub, você deverá adicionar o endereço IP do executor auto-hospedado à lista de permissões. Confira Como gerenciar endereços IP permitidos para sua organização ou Como impor políticas para configurações de segurança na sua empresa" na documentação do GitHub Enterprise Cloud.