Pular para o conteúdo
Página inicial da Latchkey
Comece grátis
Menu da documentação

Migre dos runners hospedados pelo GitHub

O guia completo de migração: o que realmente muda, os três caminhos de migração, o mapeamento exato de rótulos que a ferramenta Migrate Runners aplica, o que os PRs contêm, verificação e rollback.

por minuto
$0,0025
preço inicial, 58% abaixo do preço de tabela do GitHub
início a frio
Nova
uma máquina nova, registrada just-in-time
de YAML por job
1 linha
o rótulo runs-on: é tudo o que muda

Resumo

  1. Apenas o rótulo runs-on: muda; actions, segredos, environments e caches do lado do GitHub continuam funcionando intocados.
  2. Três caminhos: a ferramenta Migrate Runners (um PR por repositório, até 20 repos monitorados por passagem), uma edição manual de uma linha, ou o AI Scan para uma imagem sob medida.
  3. A ferramenta mapeia rótulos Ubuntu padrão para latchkey-small e nunca toca jobs Windows ou macOS, rótulos não reconhecidos ou expressões ${{ }}.
  4. O rollback é um único revert: desfaça o PR de migração e os jobs voltam a ser roteados para os hospedados pelo GitHub imediatamente.

Migrar para os runners do Latchkey é uma mudança de roteamento, não uma reescrita. O rótulo runs-on: é a única coisa que decide qual runner pega um job, então é a única coisa que uma migração toca. Todo o resto continua funcionando exatamente como antes: as actions que você chama, os segredos que o GitHub injeta, seus environments e regras de proteção, e os caches do lado do GitHub. E os rótulos hospedados pelo GitHub continuam funcionando lado a lado com os rótulos latchkey-*, então nada força uma virada completa.

O que muda e o que continua funcionando#

O que muda
  • O rótulo runs-on: de cada job que você migra
O que continua funcionando sem mudanças
  • Actions do Marketplace e personalizadas
  • Segredos de repositório, de environment e de organização
  • Environments e suas regras de proteção
  • Caches armazenados do lado do GitHub, incluindo actions/cache

Antes de começar#

Pré-requisitos

Três formas de migrar#

Os três caminhos se compõem: a maioria das equipes edita um workflow à mão como piloto, migra em massa com a ferramenta e recorre ao AI Scan no punhado de repositórios que merecem uma imagem própria.

CaminhoMelhor para
Ferramenta Migrate RunnersMigração em massa: até 20 repositórios monitorados por passagem, um PR revisável para cada
Editar runs-on: à mãoUm único workflow, um job piloto ou rótulos que a ferramenta não reconhece
AI ScanRepositórios que merecem uma imagem personalizada sob medida em vez de um preset

Caminho 1: a ferramenta Migrate Runners#

app.latchkey.dev / acme / runners

A página Runners mostra o painel Runner types, cujo rodapé diz Already have workflows on GitHub-hosted runners? Migrate them to Latchkey runners in a few clicks., ao lado de um botão Migrate runners. O diálogo Migrate runners abre sobre a página escurecida: Pick the monitored repos you want to migrate. We'll open one PR per repo that swaps every supported runs-on: label to a Latchkey runner. Anything we can't map (Windows, exotic self-hosted) is left untouched. Ele lista três repositórios monitorados, acme/api, acme/web e acme/worker, com 0/20 selecionados. acme/api é escolhido (1/20, Open migration PR), depois acme/web (2/20, Open migration PRs). O botão é pressionado e mostra Opening PRs… enquanto o botão de fechar do diálogo aguarda. O diálogo termina em Opened 2 pull requests. Merge each on your schedule., listando acme/api #431 e acme/web #92, cada um com View PR.

FIG. 3.3-ACada repositório ganha seu próprio pull request, que só troca os rótulos runs-on; nada muda até sua equipe fazer o merge, e reverter esse pull request é o rollback. Escolha até 20 repositórios monitorados por passagem.

A ferramenta tem dois pontos de entrada, e ambos abrem o mesmo diálogo: Migrate runners no rodapé do painel Runner types na página de Runners e Migrate runners no painel Repositories da aba Code hosts em Settings. Abrir PRs de migração requer um papel de owner ou admin em uma conta de organização.

01
Escolha repositórios
Até 20 repos monitorados por passagem, acompanhados pelo contador de N/20 selecionados
02
Abra PRs de migração
Um clique em Open migration PRs; o Latchkey abre um pull request por repositório
03
Revise e faça merge
"Opened N pull requests. Merge each on your schedule."

Nada em um repositório muda até sua equipe fazer merge do pull request dele. Se um repositório já tiver um PR de migração aberto, a ferramenta o vincula em vez de abrir um duplicado; se não sobrar nada para trocar, ela mostra um estado Nothing to migrate. Com mais de 20 repositórios para mover, migre em passagens.

O mapeamento exato que a ferramenta aplica#

No seu workflowO que o PR faz
ubuntu-latest, ubuntu-24.04, ubuntu-22.04Trocado para latchkey-small, o tamanho de menor custo
Outras especificações de tamanho LinuxTrocadas para o menor tamanho do Latchkey que atenda à sua CPU e memória
Jobs Windows e macOSDeixados intocados
Rótulos self-hosted que a ferramenta não reconheceDeixados intocados
Qualquer linha contendo uma expressão ${{ }}, como ${{ matrix.os }}Deixada intocada

As linhas intocadas são deliberadas: jobs que a ferramenta não consegue rotear com confiança continuam rodando exatamente onde rodam hoje, então você pode migrar sua frota Linux agora e deixar workflows de SO misto intactos com segurança. Qualquer coisa que a ferramenta pule ainda pode ser movida à mão quando você estiver pronto.

O que cada pull request contém#

Cada PR reescreve as linhas runs-on: e nada mais; como o próprio corpo do PR coloca, "Only runs-on: lines were touched. Every other line in each file is byte-identical." A única exceção: quando a migração também injeta passos de cache do Latchkey, esses passos são as únicas adições além das linhas runs-on, e o corpo diz isso. Uma tabela de mapeamento antes e depois para cada arquivo mostra exatamente o que mudou, então a revisão leva minutos, não dias.

Caminho 2: edite um único workflow à mão#

Para um workflow, a mudança é uma linha por job, e ambas as formas de rótulo roteiam de forma idêntica:

yaml
jobs:
  test:
    runs-on: latchkey-small
yaml
jobs:
  test:
    runs-on: [self-hosted, latchkey-small]

A versão passo a passo deste caminho, incluindo verificar a primeira execução e escolher um tamanho, é Execute seu primeiro job.

Caminho 3: AI Scan, para repos que merecem uma imagem própria#

Alguns repositórios valem mais do que uma troca de rótulo. O AI Scan lê os workflows que um repositório realmente executa e propõe uma configuração de runner personalizada com um formato sob medida e uma imagem que pré-instala a cadeia de ferramentas do repo, então os jobs pulam seus passos de setup por completo. Se isso soa como um dos seus, comece em Runners personalizados com AI Scan e migre esse repositório para o rótulo personalizado dele em vez de um preset.

Uma estratégia incremental#

Você não precisa de uma migração de uma só vez, e sugerimos evitá-la. Comece com um repositório de baixo risco, idealmente um instável ou lento, onde minutos mais baratos, captação mais rápida e autorreparo são mais visíveis, e deixe-o rodar por uma semana antes de comprometer a frota.

01
Piloto
Migre à mão um workflow de baixo risco: uma linha de YAML
02
Acompanhe por uma semana
Compare duração, custo e reparos na página Runs
03
Migre em massa
Abra PRs de migração para o restante da frota, até 20 repos por passagem

Jobs que precisam de GPU, Windows, macOS ou hosts arm64 permanecem nos hospedados pelo GitHub ou em outros runners, e isso é normal indefinidamente: o runs-on é decidido por job, então um workflow pode misturar jobs do Latchkey e hospedados pelo GitHub livremente.

Verifique após o merge#

01
Confira onde o job rodou

Na visualização de execução do GitHub, o nome do runner do job confirma que uma máquina do Latchkey o pegou, em vez de uma hospedada pelo GitHub. Espere um nome novo a cada execução: os runners são de uso único por design.

02
Veja os minutos chegarem

Os minutos dos jobs migrados são acumulados contra o nível gratuito do seu plano. A página Billing mostra o progresso do nível gratuito e o custo estimado até agora, e a página Cost acompanha o gasto com runners do Latchkey; detalhes em Uso de runner e minutos gratuitos.

Revertendo#

O rollback é a mesma mudança de uma linha ao contrário: reverta o PR de migração e os jobs voltam a ser roteados para os runners hospedados pelo GitHub imediatamente. Não há mais nada para desfazer, nenhum agente para desinstalar e nenhuma configuração para limpar, e o repositório permanece monitorado, mas o dashboard mostra apenas os jobs que o Latchkey atendeu, então os jobs que voltam para os runners hospedados pelo GitHub deixam de aparecer nele.

Perguntas comuns#

Q.01Preciso mudar meus segredos?

Não. O GitHub injeta seus segredos do Actions no job em tempo de execução nos runners do Latchkey exatamente como faz nos hospedados pelo GitHub. Nada é reconfigurado, e o Latchkey nunca lê os valores deles.

Q.02O actions/cache continua funcionando?

Sim, sem mudanças. Para saves e restores mais rápidos nos runners do Latchkey, a action de cache do Latchkey (latchkey-dev/cache-action@v1) usa um passo de restore e um passo de save no lugar de actions/cache, com suas entradas path e key; veja Cache de dependências.

Q.03Posso misturar runners do Latchkey e hospedados pelo GitHub?

Sim, livremente e por tempo indeterminado. O runs-on é decidido por job, então cada job em um workflow pode rodar onde encaixar melhor.