# Referência de executores auto-hospedados Encontre informações sobre como configurar e usar 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](#supported-operating-systems) e [Arquiteturas de processador com suporte](#supported-processor-architectures). * 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 #### macOS * macOS 11.0 (Big Sur) ou posterior ### 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á. ## 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 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](/pt/enterprise-server@3.22/actions/concepts/runners/actions-runner-controller) e [Suporte para o Controlador do Executor de Ações](/pt/enterprise-server@3.22/actions/concepts/runners/support-for-arc). ### 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](https://github.com/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. > \[!WARNING]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](/pt/enterprise-server@3.22/actions/how-tos/manage-runners/self-hosted-runners/monitor-and-troubleshoot#reviewing-the-self-hosted-runner-application-log-files). Para adicionar um executor efêmero ao seu ambiente, inclua o parâmetro `--ephemeral` ao registrar o executor usando `config.sh`. Por exemplo: ```shell ./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. > \[!NOTE] > 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](/pt/enterprise-server@3.22/rest/actions/self-hosted-runners). ### 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: ```shell ./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`](https://github.com/actions/runner/releases). Para saber mais, confira [Configurar notificações](/pt/enterprise-server@3.22/subscriptions-and-notifications/get-started/configuring-notifications#about-custom-notifications). Para obter instruções sobre como instalar a última versão do executor, confira as instruções de instalação da [última versão](https://github.com/actions/runner/releases). > \[!WARNING] 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`](/pt/enterprise-server@3.22/webhooks/webhook-events-and-payloads#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](/pt/enterprise-server@3.22/webhooks/webhook-events-and-payloads#workflow_job). * Para saber como trabalhar com webhooks, confira [Documentação de Webhooks](/pt/enterprise-server@3.22/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](/pt/enterprise-server@3.22/rest/actions/self-hosted-runners). 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`](/pt/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes). * Para repositórios públicos, use um token de acesso com o [`public_repo` escopo](/pt/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes). * Para organizações, use um token de acesso que possua o escopo [`admin:org`](/pt/enterprise-server@3.22/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes). 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](/pt/enterprise-server@3.22/rest/actions/self-hosted-runners). 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](https://github.com/actions/runner). 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](/pt/enterprise-server@3.22/admin/managing-github-actions-for-your-enterprise/managing-access-to-actions-from-githubcom/about-using-actions-in-your-enterprise). 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](/pt/enterprise-server@3.22/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-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 copy 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](/pt/enterprise-server@3.22/rest/meta/meta). ```shell copy github.com *.github.com *.githubusercontent.com ghcr.io ``` > \[!NOTE] > 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.