# 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.

Source: https://latchkey.dev/pt/documentation/migrate-from-github-hosted

## Summary

- Apenas o rótulo `runs-on:` muda; actions, segredos, environments e caches do lado do GitHub continuam funcionando intocados.
- 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.
- 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 `${{ }}`.
- 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

## Antes de começar

**Pré-requisitos**
- [ ] O GitHub App do Latchkey está instalado na minha organização
- [ ] Os repositórios que quero migrar estão monitorados no Latchkey
- [ ] Meu trial ou assinatura está ativo

## 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.

| Caminho | Melhor para |
| --- | --- |
| Ferramenta **Migrate Runners** | Migração em massa: até 20 repositórios monitorados por passagem, um PR revisável para cada |
| Editar `runs-on:` à mão | Um único workflow, um job piloto ou rótulos que a ferramenta não reconhece |
| [AI Scan](/documentation/custom-runners) | Repositórios que merecem uma imagem personalizada sob medida em vez de um preset |

### Caminho 1: a ferramenta Migrate Runners

A ferramenta tem dois pontos de entrada, e ambos abrem o mesmo modal: o item **Migrate Runners** na barra lateral do dashboard e o CTA no rodapé do cartão Runner Types na [página de Runners](/documentation/runners-dashboard). Abrir PRs de migração requer um papel de owner ou admin.

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 workflow | O que o PR faz |
| --- | --- |
| `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04` | Trocado para `latchkey-small`, o tamanho de menor custo |
| Outras especificações de tamanho Linux | Trocadas para o menor tamanho do Latchkey que atenda à sua CPU e memória |
| Jobs Windows e macOS | Deixados intocados |
| Rótulos self-hosted que a ferramenta não reconhece | Deixados 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:

A versão passo a passo deste caminho, incluindo verificar a primeira execução e escolher um tamanho, é [Execute seu primeiro job](/documentation/run-your-first-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](/documentation/custom-runners) 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.

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

1. **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.
2. **Veja os minutos chegarem** Os minutos dos jobs migrados são acumulados contra o nível gratuito do seu plano. O modal de cobrança mostra o progresso do nível gratuito e o custo estimado até agora, e a página de [Análise de custo](/documentation/cost-analysis) acompanha o gasto com runners do Latchkey ao lado do seu gasto com o GitHub; detalhes em [Uso de runner e minutos gratuitos](/documentation/runner-usage-and-free-minutes).

## 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, então suas análises continuam de qualquer forma.

## Perguntas comuns

### Preciso 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.

### O 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`) é um upgrade de troca direta; veja [Cache de dependências](/documentation/dependency-caching).

### Posso 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt