# Runners personalizados com AI Scan

> Crie configurações de runner sob medida com seus próprios rótulos: deixe a IA escanear seus workflows e propor o formato, depois use o rótulo como qualquer preset.

Source: https://latchkey.dev/pt/documentation/custom-runners

## Summary

- O **AI Scan** analisa seus workflows e propõe uma configuração sob medida com seu próprio rótulo `latchkey-<name>`.
- Builds de imagem costumam levar 10-15 minutos; o resultado típico é builds 30-50% mais rápidos, porque nada precisa ser instalado no início do job.
- Jobs que apontam para o novo rótulo ficam na fila até o build da imagem terminar; você é notificado quando ele está pronto.
- Limites: 2 no Developer e no Launch, 10 no Scale, ilimitado no Enterprise; runners personalizados são cobrados pela tarifa do xlarge ($0.0200/min).

Quando os quatro presets não encaixam (uma suíte de integração faminta por memória, uma compilação limitada por CPU), crie uma **configuração de runner personalizada** com seu próprio rótulo `latchkey-<name>` e um formato que você escolhe. O caminho mais rápido é o **AI Scan** na [página de Runners](/documentation/runners-dashboard).

## Preset ou personalizado?

O fator decisivo é o formato, não o ajuste fino de custo. Runners personalizados são cobrados pela tarifa do xlarge ($0.0200/min) independentemente do formato que você escolher, então um preset é quase sempre a opção mais barata quando algum encaixa. Um exemplo trabalhado usando os preços publicados: uma suíte de testes que precisa de 32 GB de memória encaixa no `latchkey-large` (8 vCPU / 32 GB) a $0.0100/min, enquanto um formato personalizado otimizado para memória com os mesmos 32 GB é cobrado a $0.0200/min. Vá de personalizado porque nenhuma proporção de preset funciona para o job, não para economizar uma vCPU.

Configurações personalizadas também são um recurso limitado na maioria dos planos (2 no Developer e no Launch, 10 no Scale, ilimitado no Enterprise), então gaste-as em cargas de trabalho genuinamente distintas, em vez de variantes menores do mesmo formato. As contagens por plano estão em [Limites e concorrência](/documentation/runner-limits).

## Como o AI Scan funciona

Na [página de Runners](/documentation/runners-dashboard), clique em **AI Scan Runners** e escolha um dos seus repositórios monitorados; a lista é pesquisável e mostra o nome de cada repo, a linguagem principal e se ele é privado. Clique em **Scan Repository** e o progresso aparece ao vivo em três passos (escaneando o repositório, analisando a stack técnica, gerando a configuração) com um cronômetro decorrido.

Você não precisa assistir. **Run in background** fecha o modal e o scan continua rodando no servidor; uma pílula de progresso na página de Runners acompanha cada scan ativo por **Queued**, **Scanning repository**, **Optimizing workflows** e **Ready for review**, com ações para visualizar, revisar e personalizar, ou aprovar em um clique.

## Lendo os resultados

Os resultados abrem com o nome do repo e uma **porcentagem geral de confiança**, a certeza autoavaliada da IA sobre a detecção e a configuração. O scan é baseado em evidências: ele lê os workflows que você de fato executa, seus manifestos de dependência e seus passos de build em vez de pedir que você adivinhe números de CPU e memória, e nada é criado até você revisar e aceitar. Trate a pontuação como exatamente isso, um indicativo de quão de perto olhar antes de aceitar.

- A seção **Detected Tech Stack** agrupa achados sob linguagens, frameworks, ferramentas de build e gerenciadores de pacotes. Cada item mostra seu nome, a versão quando detectada e um selo de confiança: High a 80%+ de confiança, Medium a 50%+, Low abaixo de 50%, cada um com a porcentagem exata.
- Um **indicador de monorepo** aparece quando o scan encontra um; o runner é dimensionado para o subpacote mais exigente.
- Abaixo disso está a **configuração proposta**: um nome de runner gerado, um tamanho recomendado, os runtimes e versões a pré-instalar, caches a configurar, variáveis de ambiente, imagens Docker a pré-baixar e um resumo de notas em linguagem simples explicando as escolhas.

### Resolução de pacotes

Antes de você aprovar qualquer coisa, os pacotes detectados são classificados em três baldes, para que não haja surpresas sobre o que a imagem contém:

| Balde | O que significa |
| --- | --- |
| Já na imagem base do runner | A ferramenta vem em toda imagem de runner do Latchkey, com versão fixada. Nada extra a instalar. |
| Será adicionado ao seu runner | A ferramenta é embutida na sua imagem personalizada, com um tempo estimado de build em minutos exibido. |
| Mantido no YAML do workflow | O Latchkey não pode pré-embutir esta ferramenta, então ela permanece como um passo de instalação em tempo de execução do CI. |

## Aprovar e construir

**Approve & Build** cria o runner e inicia a construção da sua imagem; **Skip scan results** descarta a recomendação em vez disso. O runner aparece imediatamente na tabela **Your runners** com um selo de status que passa de **Pending Build** para **Building** e para **Ready**, e builds costumam levar 10-15 minutos. Se um build falhar, o selo mostra **Failed** e você pode tentar de novo a partir da visão de detalhes do runner. No momento em que o build termina, você recebe a notificação "AI scan runner is ready", e a partir daí o rótulo se comporta como qualquer preset.

> **Enquanto a imagem constrói**
> Jobs que apontam para o novo rótulo antes de a imagem estar pronta esperam na fila. Você recebe uma notificação se um build falhar, e a linha da configuração na página de Runners mostra o status do build.

## O PR de otimização

O Latchkey também pode fazer a alteração de workflow por você. Ele abre um pull request no seu repo que troca os workflows para o rótulo do novo runner **e remove os passos de setup que a imagem torna redundantes**, já que essas ferramentas já estão instaladas quando o runner inicializa. Um banner na página de Runners anuncia os workflows otimizados com um botão **View Pull Request**. Resultado típico após o merge: builds 30-50% mais rápidos, porque nada precisa ser instalado no início do job. O PR troca jobs Linux; jobs Windows e macOS são deixados intocados.

## As regras

| Aspecto | Regra |
| --- | --- |
| Rótulo | `latchkey-<name>`: letras minúsculas, dígitos, hifens; não pode colidir com os nomes dos presets |
| Formato | Perfis de CPU/memória nas famílias general, compute e memory-optimized |
| Disco | 100 a 500 GB |
| Quantos | Developer e Launch: 2 configurações personalizadas, Scale: 10, Enterprise: ilimitado |
| Cobrança | Runners personalizados são cobrados pela tarifa do xlarge ($0.0200/min) |

Uma sugestão de nomenclatura: nomeie o rótulo pela carga de trabalho, como em `latchkey-integration-xl`, em vez de pelo formato. Um nome de carga de trabalho permanece verdadeiro no arquivo de workflow mesmo que as necessidades do job mudem, e diz ao próximo leitor para que serve o runner.

## Usando

```.github/workflows/integration.yml
jobs:
  integration:
    runs-on: latchkey-integration-xl   # your custom label
    steps:
      - uses: actions/checkout@v4
      - run: make integration-test
```

Todo o resto se comporta como um preset: máquinas efêmeras de job único, autorreparo incluído, minutos contabilizados contra seu plano.

## Mantenha a imagem sincronizada

O cartão **AI Scan Source** do painel de detalhes mostra o repositório de origem, quando foi escaneado pela última vez e um botão **Rescan Repository**. Os resultados do rescan retornam como um diff: pacotes adicionados, pacotes removidos e qualquer alteração no tamanho recomendado. **Apply Changes** atualiza a configuração e reconstrói a imagem; **Dismiss** deixa tudo como está. Se nada mudou, o painel lhe diz que o runner já está atualizado.

## Histórico de builds e configurações

O painel de detalhes lista os **últimos 10 builds de imagem** com status (pendente, construindo, bem-sucedido ou falhado), horário de início, duração do build e a mensagem de erro de qualquer falha, para que, quando um build falhar, você possa ver o porquê sem abrir um chamado de suporte.

Cada runner pode ser renomeado, receber rótulos extras, ter um limite de **Max Concurrent** (0 significa ilimitado), ser alternado como ativo ou inativo, ou excluído com confirmação. Ações de gerenciamento estão disponíveis para papéis da organização com permissões de gerenciamento; todos os demais veem os mesmos detalhes somente para leitura.

### O que o AI Scan faz?

Analisa seus workflows e propõe uma configuração de runner do tamanho certo, com seu próprio label `latchkey-<nome>`, pré-instalando o que seus jobs realmente usam. Como nada é instalado no início do job, o resultado típico é um build de 30 a 50 por cento mais rápido.

### Quanto tempo leva para construir a imagem de um runner personalizado?

Normalmente de 10 a 15 minutos. Jobs que apontam para o novo label ficam na fila até o build terminar, em vez de falhar, e você é notificado quando a imagem fica pronta, então é seguro fazer o merge da mudança no workflow antes do build concluir.

### Quantos runners personalizados posso ter e quanto custam?

Dois no Developer e no Launch, dez no Scale, ilimitados no Enterprise. Runners personalizados são cobrados pela tarifa xlarge de US$ 0,0200 por minuto, independentemente do tamanho configurado, então a economia vem de jobs mais curtos e não de uma tarifa menor.

---

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