Usar os executores auto-hospedados em um fluxo de trabalho

Você pode direcionar executores auto-hospedados para uso em um fluxo de trabalho com base nos rótulos atribuídos aos executoresou na associação ao grupo ou em uma combinação dessas duas opções.

Sobre os rótulos de executores auto-hospedados

As etiquetas permitem que você envie trabalhos do fluxo de trabalho para tipos específicos de executores auto-hospedados, com base em suas características compartilhadas. Por exemplo, se o seu trabalho exigir um componente de hardware específico ou um pacote de software, você poderá atribuir uma etiqueta personalizada a um executor e, em seguida, configurar seu trabalho para ser executado somente em executores com essa etiqueta.

Para especificar um executor auto-hospedado para seu trabalho, configure runs-on no arquivo de fluxo de trabalho com rótulos do executor auto-hospedado.

Todos os executores auto-hospedados têm o rótulo self-hosted. Se você só usar esse rótulo, isso selecionará qualquer executor auto-hospedado. Para selecionar os executores que atendem a determinados critérios, como sistema operacional ou arquitetura, recomendamos fornecer uma matriz de rótulos que começa com self-hosted (isso precisa ser listado primeiro) e, em seguida, inclui rótulos adicionais, conforme necessário. Quando você especificar uma matriz de rótulos, os trabalhos serão colocados na fila nos executores que têm todos os rótulos especificados.

Embora o rótulo self-hosted não seja necessário, recomendamos fortemente especificá-lo ao usar executores auto-hospedados para garantir que o seu trabalho não especifique acidentalmente nenhum executor atual ou futuro hospedado no GitHub.

Para saber mais sobre como criar rótulos personalizados e padrão, confira "Usar rótulos com os executores auto-hospedados".

Sobre grupos de executores auto-hospedados

Para executores auto-hospedados definidos no nívelou em níveis corporativos, você pode agrupar os executores com características compartilhadas em um só grupo de executores e depois configurar o trabalho como direcionado ao grupo de executores.

Para especificar um executor auto-hospedado para o trabalho, configure runs-on.group no arquivo de fluxo de trabalho.

Para saber mais sobre como criar e gerenciar grupos de executores, confira Gerenciar o acesso a executores auto-hospedados usando grupos.

Usar etiquetas-padrão para rotear tarefas

Um executor auto-hospedado recebe automaticamente certas etiquetas ao ser adicionado a GitHub Actions. Elas são usadas para indicar seu sistema operacional e sua plataforma de hardware:

• self-hosted: rótulo padrão aplicado a todos os executores auto-hospedados.
• linux, windows ou macOS: aplicado, dependendo do sistema operacional.
• x64, ARM ou ARM64: aplicado, dependendo da arquitetura de hardware.

Você pode usar o YAML do seu fluxo de trabalho para enviar trabalhos para uma combinação dessas etiquetas. Neste exemplo, um executor auto-hospedado que corresponde a todas as três etiquetas será elegível para executar a o trabalho:

runs-on: [self-hosted, linux, ARM64]

• self-hosted – Execute este trabalho em um executor auto-hospedado.
• linux – Use apenas um executor baseado em Linux.
• ARM64 – Use apenas um executor baseado no hardware ARM64.

As etiquetas-padrão são fixas e não podem ser alterados ou removidos. Considere usar etiquetas personalizadas caso precise de mais controle sobre o roteamento de trabalhos.

Usar etiquetas personalizadas para rotear trabalhos

Você pode criar etiquetas personalizadas e atribuí-las aos seus executores auto-hospedados a qualquer momento. As etiquetas personalizadas permitem que você envie trabalhos para determinados tipos de executores auto-hospedados, com base no modo como como são rotulados.

Por exemplo, se você tiver um trabalho que exige um tipo específico de hardware de elementos gráficos, crie um rótulo personalizado chamado gpu e atribua-o aos executores que têm o hardware instalado. Um executor auto-hospedado que corresponde a todas as etiquetas atribuídas será elegível para executar o trabalho.

Este exemplo mostra um trabalho que combina etiquetas-padrão e etiquetas personalizadas:

runs-on: [self-hosted, linux, x64, gpu]

• self-hosted – Execute este trabalho em um executor auto-hospedado.
• linux – Use apenas um executor baseado em Linux.
• x64 – Use apenas um executor baseado no hardware x64.
• gpu – esse rótulo personalizado foi atribuído manualmente aos executores auto-hospedados com o hardware de GPU instalado.

Esses rótulos operam cumulativamente. Portanto, um executor auto-hospedado precisa ter todos os quatro rótulos para estar qualificado a processar o trabalho.

Como usar grupos para rotear trabalhos

Neste exemplo, os executores do Ubuntu foram adicionados a um grupo chamado ubuntu-runners. A chave runs-on envia o trabalho para qualquer executor disponível no grupo ubuntu-runners:

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on: 
      group: ubuntu-runners
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

Como usar rótulos e grupos para rotear trabalhos

Quando você combina grupos e rótulos, o executor deve atender aos dois requisitos para ser qualificado para executar o trabalho.

Neste exemplo, um grupo de executores chamado ubuntu-runners é preenchido com executores do Ubuntu, que também receberam o rótulo ubuntu-20.04-16core. A chave runs-on combina group e labels para que o trabalho seja roteado para qualquer executor disponível dentro do grupo que também tenha um rótulo correspondente:

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on:
      group: ubuntu-runners
      labels: ubuntu-20.04-16core
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

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 runs-on do trabalho e/ou aos grupos:

• Se o GitHub encontrar um executor online e ocioso que corresponda aos rótulos runs-on do trabalho e/ou aos 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/ou aos grupos, o trabalho continuará na fila até que um executor fique online.
• Se o trabalho permanecer na fila por mais de 24 horas, o trabalho falhará.