Referência de agentes autogeridos

Requisitos para máquinas executoras auto-hospedadas

Você pode usar uma máquina como um runner auto-hospedado, desde que ela 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

Arquiteturas de processador com suporte

        `x64` – Linux, macOS e Windows.

```
        `ARM64` – Linux, macOS.
```
```
        `ARM32` – Linux.
```

Precedência de roteamento para executores auto-hospedados

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

Se GitHub encontrar um executador online e ocioso que corresponda aos rótulos e grupos runs-on do trabalho, o trabalho será então atribuído e enviado ao executador.
- 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 runner online e ocioso que corresponda aos rótulos e grupos runs-on da tarefa, a tarefa permanecerá na fila até que um runner fique online.
Se a tarefa permanecer na fila por mais de 24 horas, ela 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

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 runners 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 Runners

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.

          **Nota:** O Cliente de Conjunto de Escalonamento do Runner 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 runners. 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.

Runners 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 runner para runners efêmeros devem ser encaminhados para uma solução externa de armazenamento de logs para fins de diagnóstico e solução de problemas. 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 nenhum executor que corresponda a esse tipo estiver disponível, o trabalho não falhará imediatamente quando está sendo colocado 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 para sistemas 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 desativação das atualizações automáticas permite que você atualize a versão do executor na imagem do contêiner diretamente de acordo com sua própria programação.

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. É necessário que você crie sua própria automação de dimensionamento em resposta a esses payloads 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 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 para o escopo public_repo.
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 sua instância do GitHub Enterprise Server 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 for lançada, o aplicativo executor será atualizado automaticamente em até 24 horas.

Requisitos de comunicação com sua instância do GitHub Enterprise Server

O aplicativo do executor auto-hospedado deve estar em execução na máquina anfitriã para aceitar e executar trabalhos do GitHub Actions.
O GitHub Enterprise Server precisa aceitar as conexões que chegam dos executores via HTTP(S) no nome do host do sua instância do GitHub Enterprise Server e no subdomínio da API. Os executores devem permitir conexões de saída via HTTP(S) pelo nome do host do sua instância do GitHub Enterprise Server e o subdomínio da API.
Para que o cache funcione, o executor precisa conseguir se comunicar e baixar diretamente conteúdo do armazenamento de blobs.

Comunicação com o GitHub.com

Os executores auto-hospedados não precisam se conectar a GitHub.com, a menos que você tenha habilitado o acesso automático às ações de 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 ao GitHub.com, o computador host deverá ser capaz de fazer conexões HTTP de saída pela porta 80 ou conexões HTTPS pela porta 443. Para garantir a conectividade por HTTPS, configure o TLS para o GitHub Enterprise Server. Confira Configurando o TLS.

Se você tiver habilitado o acesso automático a ações GitHub.com, o executor auto-hospedado irá se conectar diretamente a GitHub.com para fazer o download das ações. Você deve garantir que a máquina tenha acesso adequado à rede para comunicar-se 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 a GitHub, incluindo os endereços IP e domínios dos serviços da 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.