Referência de executores auto-hospedados

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.
O computador pode se comunicar 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

Arquiteturas de processador com suporte

x64 – Linux, macOS e Windows.
ARM64 – Linux, macOS.
ARM32 – Linux.

Precedência de encaminhamento para executores auto-hospedados

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

Se o GitHub encontrar um executor online e ocioso que corresponda aos rótulos e grupos runs-on do trabalho, 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 e grupos runs-on do trabalho, 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á.

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

O Actions Runner Controller (ARC) é a implementação de referência das APIs de conjuntos de dimensionamento do GitHub e a solução baseada em Kubernetes recomendada para executores auto-hospedados de dimensionamento automático. O ARC fornece uma solução completa de dimensionamento automático, pronta para 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 do Conjunto de Dimensionamento do Executor

O cliente GitHub Actions Runner Scale Set é 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 interações de API do GitHub para conjuntos de dimensionamento, deixando o provisionamento da 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 código aberto. 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.

          **Nota:** o Cliente do Conjunto de Dimensionamento do Executor não substitui o Actions Runner Controller (ARC), que continua sendo a implementação de referência das APIs de conjunto de dimensionamento e a solução recomendada do Kubernetes para executores de escalonamento automático. 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

O GitHub recomenda a implementação do escalonamento automático com executores auto-hospedados efêmeros; o escalonamento automático com executores auto-hospedados persistentes não é recomendado. Em determinados 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, isso pode ser garantido porque GitHub atribui apenas 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ário implantar executores efêmeros, o GitHub recomenda que os logs dos executores sejam encaminhados e preservados externamente antes da implantação de 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 cancelará automaticamente o registro do executor depois que ele processar um trabalho. Em seguida, você poderá criar a sua própria automação que limpa o executor 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. Novas funcionalidades no GitHub Actions exigem alterações no serviço GitHub Actions e no software do executor. O executor pode não ser capaz de processar corretamente trabalhos que aproveitam os novos recursos GitHub Actions sem uma atualização de 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.

Para saber mais sobre o webhook workflow_job, confira Eventos e cargas de webhook.
Para saber como trabalhar com webhooks, confira Documentação de Webhooks.

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 se autenticar na API, sua implementação de dimensionamento automático pode usar um token de acesso ou um GitHub aplicativo.

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 autenticar usando um GitHub aplicativo, ele deve receber 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

Os executores auto-hospedados se conectam ao sua instância do GitHub Enterprise Server para receber atribuições de trabalhos e baixar novas versões do aplicativo do 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 for lançada, o aplicativo executor será atualizado automaticamente dentro de 24 horas.

Requisitos para comunicaçãosua instância do GitHub Enterprise Server

O aplicativo do executor auto-hospedado deve estar em execução no computador host para aceitar e executar trabalhos GitHub Actions.

          O GitHub Enterprise Server deve aceitar conexões de entrada dos seus executores via HTTP(S) no nome do host e no subdomínio da API do sua instância do GitHub Enterprise Server e seus executores devem permitir conexões de saída via HTTP(S) para o nome do host e o subdomínio da API do sua instância do GitHub Enterprise Server.

Para que o cache funcione, o executor precisa conseguir se comunicar e baixar diretamente conteúdo do armazenamento de blobs.

Comunicação com GitHub.com

Os executores auto-hospedados não precisam se conectar ao GitHub.com, a menos que você tenha habilitado o acesso automático a ações do GitHub.com para GitHub Enterprise Server. Para saber mais, confira Sobre como usar ações na sua empresa.

Se você quiser que o executor se conecte a GitHub.com, o computador host deve ser capaz de realizar conexões HTTP de saída pela porta 80 ou conexões HTTPS pela porta 443. Para garantir a conectividade via HTTPS, configure o TLS para GitHub Enterprise Server. Confira Configurando o TLS.

Se você tiver habilitado o acesso automático às ações do GitHub.com, o executor auto-hospedado se conectará diretamente ao GitHub.com para baixar ações. Você deve garantir que o computador tenha o acesso de rede apropriado para se comunicar com as GitHub URLs listadas abaixo.

Shell

github.com
api.github.com
codeload.github.com

github.com
api.github.com
codeload.github.com

Você pode usar a API REST para obter metainformações sobre GitHub, incluindo os endereços IP e os detalhes de domínio dos serviços GitHub. A seção actions_inbound da API dá suporte a nomes de domínios totalmente qualificados e domínios curinga. Domínios totalmente qualificados especificam um nome de domínio completo (por exemplo, example.github.com), enquanto domínios curinga usam um * para representar vários subdomínios possíveis (por exemplo, *.github.com). Um exemplo dos requisitos do executor auto-hospedado que usa domínios curinga foi listado abaixo. Para saber mais, confira Pontos de extremidade da API REST para metadados.