Como mudar de fornecedor de runners de GitHub Actions: etiquetas, caches, segredos, faturação e fallback

Este guia é neutro em relação a fornecedores. Explica o que muda quando troca de fornecedor de runners de GitHub Actions, o que falha com mais frequência e como voltar atrás. Nós desenvolvemos o CRACI, um dos fornecedores; aparece onde se aplica um facto documentado e numa secção própria no fim. Para escolher primeiro um fornecedor, consulte fornecedores de runners de GitHub Actions comparados e alternativas aos runners alojados no GitHub.

O que muda e o que fica quando muda de fornecedor

O GitHub Actions tem duas metades. O GitHub é o plano de controlo: guarda o repositório e os ficheiros de workflow, dispara os triggers, guarda os segredos, atribui os jobs, mostra os logs e as verificações, conserva os artefactos e emite os tokens OIDC. O runner de CI é onde um job é executado: uma máquina com uma imagem, CPU, disco, um caminho de rede para a internet e normalmente uma cache local. O GitHub atribui um job a um runner, entrega os segredos do job quando este começa, e o runner envia os logs de volta.

Um fornecedor de runners substitui apenas a segunda metade.

Elemento	Fica no GitHub	Passa para o fornecedor
Repositório, ficheiros de workflow, triggers	Sim	Não
Armazenamento de segredos	Sim	Os segredos são entregues à máquina do fornecedor no início do job
Atribuição de jobs, logs, interface de verificações	Sim	O runner envia os logs de volta
Artefactos de actions/upload-artifact	Sim	Não
Emissor do token OIDC	Sim	Não, mas o token indica que o runner é self-hosted
Máquina, imagem, CPU, memória, disco	Não	Sim
Caminho de rede de saída e endereços IP	Não	Sim
Armazenamento da cache	Depende do fornecedor	Depende do fornecedor
Faturação por minuto dos jobs movidos	Não	Sim

Um runner de terceiros regista-se no GitHub como runner self-hosted. É por isso que lhe são aplicadas as regras do GitHub para runners self-hosted: como as etiquetas encaminham os jobs, como os runner groups limitam o acesso, como o token OIDC o descreve e como o GitHub o fatura.

A alteração de runs-on e as etiquetas

O GitHub procura um runner que corresponda às etiquetas runs-on e aos grupos do job. Se nenhum runner correspondente estiver online, o job fica em fila até que um fique disponível; se um runner atribuído não aceitar o job em 60 segundos, o job volta à fila; e um job que fique em fila durante mais de 24 horas falha (referência do GitHub sobre runners self-hosted). Um erro de escrita numa etiqueta, ou uma app do fornecedor que não esteja instalada no repositório, manifesta-se como um job que nunca arranca.

Os fornecedores codificam a máquina de uma de duas formas:

• Na etiqueta. O Ubicloud usa etiquetas como ubicloud-standard-2, o Blacksmith blacksmith-2vcpu-ubuntu-2404 e o Avrea avrea-ubuntu-latest-2-vcpu, com arm na etiqueta para máquinas ARM. Mudar de tamanho significa mudar de etiqueta.
• Num passo de setup. O CRACI usa uma única etiqueta, runs-on: craci, e o passo cracicorp/setup@v1 seleciona o tamanho (1 a 32 unidades de computação de 1 vCPU e 3 GB, 2 por predefinição), a imagem, a política de rede ou um modelo de runner da organização pelo respetivo slug. Se o CRACI não conseguir interpretar um input, executa o ambiente predefinido e escreve um aviso no log do job; uma imagem ou um modelo desconhecido é rejeitado.

Faça da mudança uma única variável

Coloque a etiqueta numa variável de repositório ou de organização em vez de a escrever diretamente no workflow. Mudar para a frente ou para trás passa a ser uma alteração de definições, e não um pull request em todos os repositórios.

jobs:
  build:
    # Falls back to GitHub-hosted when the variable is not set
    runs-on: ${{ vars.LINUX_RUNNER || 'ubuntu-latest' }}
    steps:
      - uses: actions/checkout@v7
      - run: make build

  deploy:
    needs: build
    # Stays on GitHub-hosted until you decide to move it
    runs-on: ubuntu-latest
    steps:
      - run: ./deploy.sh

A escolha é feita por job, pelo que os jobs de build e de teste podem mudar enquanto um job de implementação fica. As variáveis podem ser definidas ao nível da organização e substituídas por repositório, pelo que uma definição pode mover um grupo de repositórios e um repositório pode ficar de fora.

Workflows reutilizáveis

Se o mesmo pipeline estiver copiado em muitos repositórios, passe-o para um workflow reutilizável que leia o runner a partir de um input ou de uma variável. Alterar runs-on aí altera todos os repositórios que o chamam. Os rulesets podem exigir que um workflow seja executado nos repositórios de uma organização, o que mantém a versão partilhada em uso.

Imagens de runner: compatibilidade e fixação

A imagem alojada do GitHub traz um grande conjunto de ferramentas pré-instaladas e uma tool cache alojada. Os fornecedores oferecem uma imagem compatível com a do GitHub ou uma mais leve. Os jobs dependem muitas vezes de coisas que nunca declaram:

• versões de linguagens e ferramentas de linha de comandos pré-instaladas;
• sudo sem palavra-passe, e systemd para serviços iniciados com systemctl;
• um daemon Docker em execução, com Buildx e Compose;
• a tool cache alojada que as actions setup-* leem antes de descarregar;
• espaço livre em disco para builds grandes.

Regra de decisão: comece pela imagem compatível com o GitHub do fornecedor. Passe um job para uma imagem leve só depois de estar verde, e acrescente passos setup-* explícitos para tudo o que usava implicitamente.

Fixação: ubuntu-latest passa para uma nova versão ao ritmo do calendário do GitHub, e ubuntu-24.04 fixa a versão do sistema operativo, não as versões dos pacotes. Fixe o que importa dentro do job: setup actions com versões explícitas e imagens de contentor por digest. Pergunte a cada fornecedor o que permite fixar. A própria aplicação de runner tem de se continuar a atualizar para comunicar com o GitHub.

No CRACI, as imagens são o CRACI Slim em x86-64 e ARM64 (Ubuntu 24.04, sem systemd) e uma imagem Ubuntu 24.04 totalmente compatível com GitHub Actions, selecionada como ubuntu-24.04 ou ubuntu-latest, que acompanha a imagem de runner Ubuntu 24.04 do GitHub e inclui a tool cache alojada. Todas as imagens têm Docker Engine, Buildx e Compose v2.

Caches: o que passa e o que começa a frio

As primeiras execuções num novo fornecedor são muitas vezes mais lentas, e o motivo habitual é uma cache fria, não uma máquina lenta. A forma como o actions/cache funciona determina o que vê (README do actions/cache):

• Uma entrada é encontrada pela sua chave e por uma versão, que é um hash dos caminhos em cache e da ferramenta de compressão.
• As entradas têm âmbito por branch; as entradas do branch predefinido estão disponíveis para os outros branches.
• Por predefinição, um repositório pode guardar até 10 GB de caches antes de as entradas mais antigas serem removidas. Os administradores do repositório e os proprietários da organização ou da enterprise podem aumentar o limite; o uso acima de 10 GB é faturado à conta (GitHub sobre dependency caching).
• Uma cache guardada em Windows não é restaurada noutro sistema operativo, nem o contrário, salvo se enableCrossOsArchive estiver definido; uma ferramenta de compressão diferente também dá uma versão diferente.

Os fornecedores servem a cache de uma de duas formas:

Modelo	Primeiras execuções	Contrapartida
O runner usa o serviço de cache do GitHub, tal como os runners alojados no GitHub	As entradas existentes são restauradas	O tráfego de cache atravessa a internet entre o fornecedor e o GitHub
O fornecedor serve a API de cache a partir de armazenamento junto dos seus runners	Normalmente vazia até as primeiras execuções a preencherem, salvo se o fornecedor importar as entradas do GitHub ou recorrer a elas	Restauros mais rápidos; as entradas aí escritas normalmente não são visíveis para os runners alojados no GitHub

O segundo ponto importa para frotas mistas e para reverter: se mudar um job de volta, pode começar também a frio no GitHub. Pergunte que modelo o fornecedor usa e onde ficam as entradas.

Distinguir uma cache fria de um runner lento. Imagine um build Node que guarda em cache um diretório node_modules grande. Na primeira execução num novo fornecedor, o actions/cache reporta uma falha, o passo de instalação descarrega tudo e o passo final guarda a cache. A partir da execução seguinte no mesmo branch, o passo reporta um acerto e o passo de instalação encurta. Compare execuções só depois de a cache estar quente: leia o output cache-hit e meça o passo de restauro e o passo de instalação separadamente do próprio build. Consulte como funciona a cache do GitHub Actions para chaves, âmbitos e envenenamento de cache.

No CRACI, o actions/cache funciona como hoje, e o registo do build indica, por pacote, se foi restaurado de uma cache de CI em vez de ser obtido.

Cache de camadas Docker

Mecanismo	Onde ficam as camadas	O que saber
BuildKit type=gha	A cache do GitHub Actions	As mesmas regras de âmbito e tamanho indicadas acima; precisa de um builder que o suporte
BuildKit type=registry	Uma imagem separada no seu registo	Funciona em qualquer runner e sobrevive a uma mudança de fornecedor; paga o armazenamento e a transferência do registo
Cache de camadas local do fornecedor ou disco persistente	Junto dos runners do fornecedor	Normalmente a mais rápida; fica para trás se deixar o fornecedor

Uma cache em registo é a opção portável (backends de cache do Docker):

- uses: docker/build-push-action@v7
  with:
    push: true
    tags: ghcr.io/acme/app:latest
    cache-from: type=registry,ref=ghcr.io/acme/app:buildcache
    cache-to: type=registry,ref=ghcr.io/acme/app:buildcache,mode=max

Dois jobs que comecem ao mesmo tempo restauram a mesma cache e ambos constroem as camadas que lhe faltam. Isto acontece em qualquer CI, pelo que não o interprete como um problema do fornecedor.

O CRACI oferece cache de camadas de contentor com uma cache de camadas local, uma cache de camadas remota e uma cache por bind mount.

Segredos, OIDC e credenciais cloud

O GitHub guarda os seus segredos e entrega-os ao runner que executar o job. Mover um job para um fornecedor significa confiar a esse fornecedor os segredos desse job. Pergunte:

• Cada job recebe a sua própria máquina virtual, ou um contentor num host partilhado?
• A máquina é destruída depois do job, e fica guardada alguma coisa?
• Que logs guarda o fornecedor? O GitHub oculta os segredos registados nos logs dos jobs e diz que a ocultação automática não é garantida para valores transformados; pergunte também pelos logs de sistema do próprio fornecedor.

O OIDC continua a funcionar, com um senão. É o GitHub que emite o token OIDC, não o runner, pelo que permissions: id-token: write funciona em qualquer runner. Mas a claim runner_environment do token é github-hosted ou self-hosted (referência do GitHub sobre OIDC), e num runner de terceiros é self-hosted. Uma política de confiança cloud que exija github-hosted rejeita o job. Por exemplo, um workload identity pool do Google Cloud com esta condição de atributo:

# Before: only GitHub-hosted runners in the acme organization
assertion.repository_owner == 'acme' && assertion.runner_environment == 'github-hosted'

# After: drop the runner check, and narrow by repository and branch instead
assertion.repository == 'acme/app' && assertion.ref == 'refs/heads/main'

Remover a verificação do runner alarga quem pode obter credenciais, por isso reforce outra condição ao mesmo tempo. Antes da mudança, procure runner_environment em todas as políticas de confiança cloud e configurações de workload identity.

Enviar imagens: o GITHUB_TOKEN com packages: write envia para o GitHub Container Registry a partir de qualquer runner, e os logins em registos que usam segredos guardados funcionam sem alterações.

No CRACI, a GitHub App lê o seu código e as suas execuções de Actions e gere os runners que regista para a sua organização. Cada job é executado na sua própria máquina virtual isolada, e o CRACI não guarda o seu código-fonte.

Identidade de rede: listas de IP permitidos e egress

O novo runner sai a partir de novos endereços IP. Liste tudo o que filtra por endereço de origem:

• listas de permissões de bases de dados e de repositórios de artefactos;
• APIs SaaS com restrições de IP;
• servidores SFTP de parceiros e serviços internos atrás de uma firewall.

As opções são os endereços IP de egress estáticos ou estáveis do fornecedor, ou um proxy controlado por si. É também o momento de decidir a que destinos os jobs podem chegar: uma política de egress no runner impede que uma dependência comprometida envie segredos para um host de que o build nunca precisou. Consulte política de egress no GitHub Actions.

O CRACI oferece um intervalo estável de IP de egress e uma política de egress, com negação ou permissão por defeito, validada antes de o job arrancar e que falha em modo fechado. Sem um input network, o modelo predefinido permite outras ligações de saída, pelo que o controlo de egress é algo que configura.

Frotas mistas: mova o Linux, mantenha o macOS e o iOS onde estão

O runner é escolhido por job, pelo que um workflow pode executar os seus jobs Linux num fornecedor e os seus jobs macOS em runners alojados no GitHub. Os artefactos enviados com actions/upload-artifact são guardados pelo GitHub, pelo que um job num runner pode passar ficheiros a um job noutro.

jobs:
  backend:
    runs-on: ${{ vars.LINUX_RUNNER || 'ubuntu-latest' }}
    steps:
      - uses: actions/checkout@v7
      - run: ./gradlew test

  android:
    runs-on: ${{ vars.LINUX_RUNNER || 'ubuntu-latest' }}
    steps:
      - uses: actions/checkout@v7
      - run: ./gradlew assembleRelease
      - uses: actions/upload-artifact@v7
        with:
          name: android
          path: app/build/outputs/apk/release/

  ios:
    # Signing and the iOS build stay on GitHub-hosted macOS
    runs-on: macos-latest
    needs: backend
    steps:
      - uses: actions/checkout@v7
      - run: xcodebuild -scheme App -configuration Release archive

Os jobs que ficam no GitHub continuam a consumir a utilização incluída no seu plano e são faturados pelo GitHub acima dela. Hoje, o CRACI executa Linux em x86-64 e ARM64, com Windows e macOS no roadmap, pelo que uma frota mista com o CRACI significa CRACI para Linux e runners alojados no GitHub para o resto.

Fallback quando um fornecedor está em baixo

O GitHub não tem fallback integrado entre etiquetas de runner. Se nenhum runner para a etiqueta estiver online, o job espera e, ao fim de 24 horas, falha. Prepare-se para isso:

• A mudança por variável descrita acima: volte a defini-la como ubuntu-latest e as novas execuções vão para runners alojados no GitHub.
• Uma substituição manual para execuções urgentes: um input de workflow_dispatch, lido como runs-on: ${{ inputs.runner || vars.LINUX_RUNNER || 'ubuntu-latest' }}.
• timeout-minutes nos jobs, para que um job bloqueado não retenha uma implementação durante horas.
• Monitorização do tempo em fila, para perceber quando os jobs esperam mais do que o habitual.

Pergunte a cada fornecedor se oferece um fallback automático e o que o aciona. Prepare-se também para o sentido inverso: o GitHub coloca em fila e atribui todos os jobs, pelo que uma falha do GitHub Actions também para os jobs em todos os fornecedores de runners.

Faturação: o GitHub continua a cobrar?

O GitHub não cobra por minuto pelos runners self-hosted, e os runners de terceiros registam-se como self-hosted, pelo que os minutos que mover deixam de aparecer na fatura do GitHub (faturação do GitHub Actions). O GitHub continua a faturar:

• os lugares do seu plano;
• o armazenamento de artefactos e de cache que guarda acima da quota incluída;
• os jobs que ficam em runners alojados no GitHub, acima da utilização incluída no seu plano, que não é reembolsada.

Durante o piloto paga duas faturas. Os fornecedores contam os minutos de build de formas diferentes: o GitHub arredonda cada job para cima, ao minuto inteiro, e alguns fornecedores medem ao segundo. Para dimensionar a sua utilização antes e depois, use a calculadora de custos do GitHub Actions. O CRACI cobra apenas os minutos de build: $0.002 por minuto de vCPU ($0.004 para um runner predefinido de 2 vCPU), medidos ao segundo, sem mensalidade.

Isolamento de segurança: o que perguntar a qualquer fornecedor

Pergunta	Porque importa
Uma máquina virtual por job, ou contentores num host partilhado?	Um host partilhado permite que um job comprometido chegue aos vizinhos
A máquina é destruída depois do job?	Uma máquina persistente transporta ficheiros, credenciais e processos para o job seguinte
Onde está o hardware, e quem o opera?	Localização dos dados, jurisdição e os contratos dos seus clientes
O que guarda o fornecedor, e durante quanto tempo?	Logs, caches e dados de rede podem conter material sensível
Que certificações tem?	A sua avaliação de fornecedores vai perguntar
Pode controlar o egress?	Impede que os segredos saiam através de um pacote malicioso
O que pode a sua GitHub App ler e alterar?	As permissões da app aplicam-se a todos os repositórios em que a instalar

O GitHub diz que os runners self-hosted quase nunca devem ser usados em repositórios públicos, porque qualquer pessoa pode abrir um pull request e comprometer o ambiente, e que os runners just-in-time executam no máximo um job antes de serem removidos (referência do GitHub sobre utilização segura). Uma máquina virtual nova por job responde à maior parte dessa preocupação.

As respostas do CRACI: cada job é executado na sua própria máquina virtual isolada, em infraestrutura bare-metal europeia. O sistema de gestão da segurança da informação da CRACI Corporation Oy, para o desenvolvimento e a operação da plataforma CRACI, está certificado segundo a ISO/IEC 27001 pela Into Certification, com detalhes no Trust Center. O CRACI guarda metadados de build, dados de pacotes, traços de rede, SBOM, proveniência, caches e registos de auditoria, e nunca o seu código-fonte. Consulte a que o CRACI pode aceder e segurança.

Teste primeiro num único repositório

1. Escolha um repositório com um workflow Linux representativo e executado com frequência, e não o pipeline de release.
2. Registe uma referência em runners alojados no GitHub: duração mediana e tempo em fila nas últimas 30 execuções, e minutos faturados.
3. Instale a GitHub App do fornecedor apenas nesse repositório.
4. Mude um job através da variável de repositório, num branch.
5. Execute-o pelo menos dez vezes e descarte as três primeiras como aquecimento da cache.
6. Compare a duração, o tempo em fila, a taxa de acertos de cache, as falhas e o custo; verifique os logs, o OIDC e as chamadas de saída.
7. Reverta alterando a variável e confirme que o job volta aos runners alojados no GitHub.

Métrica	Referência em runners alojados no GitHub	Fornecedor	Limiar de aprovação
Duração mediana do job			O seu objetivo, por exemplo 30% mais curta
Tempo mediano em fila			Não pior do que a referência
Taxa de acertos de cache após o aquecimento			Igual à referência
Execuções falhadas não causadas pelo código			Nenhuma
Custo por execução			Abaixo da referência
OIDC, listas de permissões e chamadas de saída			Tudo funciona

Meça a velocidade no seu próprio workflow. Cada fornecedor publica os seus próprios números, e o único que decide o seu caso é o do seu pipeline.

Onde se encaixa o CRACI

O CRACI é um runner de GitHub Actions. Substitui o runner, não o GitHub Actions: um job passa para o CRACI com runs-on: craci, os tamanhos e as imagens são definidos com cracicorp/setup@v1 ou com um modelo de runner da organização, e as execuções continuam a aparecer no GitHub. O CRACI executa builds cerca de duas vezes mais depressa do que os runners alojados no GitHub, graças a hardware mais rápido, tempos em fila mais curtos e caching.

O motivo para o escolher em vez de outros fornecedores é o que cada job deixa: uma SBOM do que o build obteve, com um estado de completude, registada sob uma política de egress que falha em modo fechado. O docs.craci.com oferece também um prompt para agentes de programação que propõe um plano de migração por job para os seus workflows. Consulte integração de CI/CD.

Quando o CRACI não é a resposta

• Precisa de runners macOS ou Windows: estão no roadmap do CRACI.
• Usa GitHub Enterprise Server, que o CRACI não suporta.
• A sua CI é GitLab CI ou Jenkins: ambos estão no roadmap.
• Os runners têm de estar na sua própria conta cloud: os runners alojados pelo cliente estão no roadmap. O RunsOn e a opção bring-your-own-cloud do WarpBuild fazem-no hoje; consulte CRACI vs RunsOn e CRACI vs WarpBuild.
• O seu principal objetivo é observabilidade e depuração de CI; consulte CRACI vs Avrea. Para operar os seus próprios runners, consulte runners geridos vs self-hosted.

Mudar de fornecedor de runners: perguntas frequentes

O que é preciso alterar para usar outro fornecedor de runners de GitHub Actions?

Instale a GitHub App do fornecedor e altere a etiqueta runs-on do job para a etiqueta do fornecedor. Os workflows, os triggers, os segredos e a interface do GitHub ficam iguais. Antes de mover jobs importantes, verifique a imagem do runner, as caches, os endereços IP de saída, as políticas de confiança cloud que usam OIDC, o fallback e a faturação.

As caches do GitHub Actions passam para um novo fornecedor de runners?

Depende de onde o fornecedor serve a cache. Se os seus runners usarem o serviço de cache do GitHub, as entradas existentes são restauradas. Se servir a API de cache a partir de armazenamento junto dos seus runners, a cache começa normalmente vazia e vai-se preenchendo nas primeiras execuções. Pergunte ao fornecedor que modelo usa e se as entradas escritas nos seus runners são visíveis para os runners alojados no GitHub.

A cache de camadas Docker funciona em runners de terceiros?

Sim, com qualquer um de três mecanismos: o backend type=gha do BuildKit, que usa a cache do Actions; uma cache em registo com type=registry, que funciona em qualquer runner; ou uma cache de camadas ou um disco persistente que o fornecedor mantém junto dos seus runners.

Posso manter os builds de macOS e iOS no GitHub enquanto os jobs Linux mudam?

Sim. O runner é escolhido por job, pelo que os jobs Linux podem ser executados num fornecedor enquanto os jobs macOS ficam em runners alojados no GitHub, no mesmo workflow. Ligue-os com needs: e passe ficheiros com actions/upload-artifact e actions/download-artifact, que o GitHub armazena.

O que acontece a um job se o runner de terceiros estiver em baixo? Há fallback?

O GitHub não tem fallback integrado entre etiquetas de runner. Um job cuja etiqueta não corresponda a nenhum runner online fica em fila e falha ao fim de 24 horas. Guarde a etiqueta numa variável de repositório ou de organização, para que voltar atrás seja uma única alteração, defina timeout-minutes e pergunte a cada fornecedor se oferece o seu próprio fallback.

Os segredos e o OIDC continuam a funcionar em runners de terceiros?

Sim. O GitHub guarda os segredos e entrega-os ao runner no início do job, e é o GitHub que emite o token OIDC, pelo que id-token: write funciona em qualquer runner. O senão: a claim runner_environment do token é self-hosted num runner de terceiros, pelo que uma política de confiança cloud que exija github-hosted rejeita o job.

O GitHub continua a faturar minutos se eu usar outro fornecedor de runners?

Não pelos jobs que mover. Os runners de terceiros registam-se no GitHub como runners self-hosted, e o GitHub indica que os runners self-hosted não têm custos por minuto. O GitHub continua a faturar lugares, o armazenamento que guarda acima da quota incluída e os jobs que ficarem em runners alojados no GitHub. O fornecedor fatura os seus próprios minutos.

Como fixo a imagem do runner para que não mude sem eu saber?

ubuntu-latest muda ao ritmo do calendário do GitHub, e ubuntu-24.04 fixa a versão do sistema operativo, mas não as versões dos pacotes. Fixe o que importa dentro do job: setup actions com versões explícitas e imagens de contentor por digest. Pergunte a cada fornecedor o que permite fixar; a própria aplicação de runner tem de se atualizar para continuar a funcionar com o GitHub.

Como são os jobs isolados uns dos outros num runner de terceiros?

Depende do fornecedor. Pergunte se cada job recebe a sua própria máquina virtual ou um contentor num host partilhado, se a máquina é destruída depois do job e o que o fornecedor guarda a seguir. Uma máquina virtual nova por job é o mais forte dos modelos comuns, porque nada de um job fica para o seguinte.

Como testo primeiro um fornecedor de runners num único repositório?

Instale a GitHub App do fornecedor num repositório, mude um job Linux executado com frequência através de uma variável de repositório num branch, execute-o pelo menos dez vezes e compare a duração, o tempo em fila, os acertos de cache, as falhas e o custo face a uma referência em runners alojados no GitHub. Para reverter, altere a variável.