Menu da documentação
Primeiros passos
Painel e análises
- Painel em resumo
- Análise de custo
- Desempenho de pipeline
- Insights de otimização
- Knowledge Base
- Conecte seu agente de IA
Runners gerenciados
- Visão geral dos runners
- Execute seu primeiro job
- A página de Runners
- Runners personalizados (AI Scan)
- Autorreparo
- Imagem e software do runner
- Limites e concorrência
Cache
Equipe e notificações
Faturamento e planos
Ajuda
Solução de problemas
Correções sintoma por sintoma: jobs travados em fila, um painel vazio, insights ausentes, login bloqueado e mais.
Cada seção abaixo é um sintoma, com suas causas na ordem em que mais vale a pena verificá-las. A maioria dos problemas se anuncia em algum lugar: um banner no painel, uma notificação no sino ou um status em um modal. Esta tabela indica onde olhar primeiro.
| Sintoma | Primeira verificação | Onde |
|---|---|---|
| Job direcionado a um runner permanece em fila | A string exata do label | Tabela de Configurações de Runner na página Latchkey Runners |
| O painel não mostra dados | Um repositório está selecionado | A barra de filtros no topo de toda página de análise |
| Sem insights de IA | O banner de processamento e a branch de análise | A página de Insights e o modal de Monitoramento |
| Lançamentos de runner bloqueados | Estado de trial, assinatura e camada gratuita | O modal de Cobrança e a notificação "Managed runner blocked" |
| Acesso subitamente bloqueado | Status da assinatura (trial encerrado, Past Due, Canceled) | A tela de ativação ou o modal de Cobrança |
Um job direcionado a um runner Latchkey permanece em fila#
Este é o sintoma universal para qualquer coisa que impeça o provisionamento de um runner. O GitHub mantém um job em "fila" até que um runner com um label correspondente o pegue, e quando o Latchkey bloqueia ou não consegue rotear um lançamento não há erro do lado do GitHub; o job simplesmente aguarda. Isso significa que o diagnóstico sempre acontece do lado do Latchkey. Faça a triagem nesta ordem:
Descarte um erro de digitação no label
O label deve ser exatamente latchkey-small, latchkey-medium, latchkey-large, latchkey-xlarge ou um dos seus labels personalizados. Como confirmar: a tabela de Configurações de Runner na página Latchkey Runners mostra as strings exatas; compare com seu arquivo de workflow caractere por caractere (um espaço perdido ou um hífen errado já basta para não corresponder). Ambas as formas de label roteiam de forma idêntica, então runs-on: latchkey-small e runs-on: [self-hosted, latchkey-small] se comportam da mesma maneira; a forma de array não é o problema.
Confirme que o repositório está monitorado
Runners gerenciados só atendem repositórios monitorados, então um job de um repo não monitorado aguarda para sempre. Como confirmar: abra o modal de Monitoramento na barra lateral do painel (donos e admins) e verifique o toggle do repositório. Se você estiver no limite de repositórios do seu plano, novos toggles são bloqueados e o modal aponta para o upgrade; veja Gerenciando repositórios.
Verifique se a configuração do runner está habilitada
Uma configuração desabilitada para de aceitar novos jobs, e jobs direcionados ao seu label ficam em fila. Como confirmar: a linha da configuração na página de Runners mostra seu estado de habilitado/desabilitado, tanto para os presets quanto para runners personalizados.
Verifique o estado de trial, assinatura e camada gratuita
Um trial expirado, uma assinatura vencida (past due ou cancelada) ou uma camada gratuita esgotada em um trial sem cartão bloqueiam todos os novos lançamentos de runner. Como confirmar: procure por uma notificação "Managed runner blocked" no sino de notificações, depois abra o modal de Cobrança: o selo de status (Trial, Active, Past Due, Canceled) e o medidor de camada gratuita indicam em qual caso você está. Assinar, ou corrigir o método de pagamento no portal do Stripe, restaura os lançamentos imediatamente; veja Uso de runners e minutos gratuitos.
Verifique se uma imagem personalizada ainda está sendo construída
Jobs direcionados a uma nova configuração personalizada aguardam até que sua imagem termine de ser construída. Como confirmar: a linha da configuração na página de Runners mostra o status do build da imagem, e você é notificado quando o runner está pronto ("AI scan runner is ready") ou se o build falhou. Veja Runners personalizados.
Verifique o teto de concorrência
Se 20 jobs já estão em execução (o limite padrão por workspace; runners quentes ociosos não contam), jobs adicionais aguardam por uma vaga. Como confirmar: isso aparece quando muitos workflows disparam ao mesmo tempo em seus repositórios, e os jobs em fila iniciam por conta própria à medida que os jobs em execução terminam. Limites mais altos estão disponíveis; veja Limites e concorrência.
O painel não mostra dados#
Um painel vazio quase sempre significa filtros ou tempo, não dados perdidos. Verifique nesta ordem:
- Nenhum repositório selecionado. A barra de filtros orienta toda página de análise, e as páginas solicitam que você escolha um repositório se nada estiver selecionado. Como confirmar: verifique o seletor de Repositório na barra de filtros no topo; se os filtros estiverem em um estado confuso, Reset filters os retorna aos padrões.
- Backfill ainda em execução. Um repositório recém-habilitado importa o histórico recente primeiro, e a maioria das equipes vê dados em poucos minutos. Como confirmar: o banner de progresso do backfill aparece no painel até que a importação seja concluída; aguarde ele desaparecer antes de avaliar as páginas.
- Nenhuma execução na janela. O backfill cobre execuções concluídas dos últimos 30 dias, e o filtro de intervalo de datas deve se sobrepor à atividade real. Como confirmar: verifique as execuções de workflow recentes do repositório no GitHub; se a última execução for anterior à janela de backfill, as páginas permanecem vazias até que novas execuções ocorram. Amplie o seletor de intervalo de datas antes de concluir que há dados faltando.
- App instalado na org errada. Se o GitHub App não estiver instalado na organização que possui os repositórios, nenhum evento chega. Como confirmar: no GitHub, abra as Settings da organização, depois GitHub Apps, e verifique se o Latchkey está listado lá. Corrija instalando na organização correta; veja Instale o GitHub App.
Nenhum insight de IA está aparecendo#
A geração de insights é automática e orientada a eventos; não há botão para apertar. O agente é executado após o backfill inicial de um repositório recém-monitorado, quando um arquivo de workflow muda na branch de análise, em falhas consecutivas repetidas, em um pico de custo e em degradação de desempenho. Então "sem insights" geralmente significa que o gatilho ainda não disparou, ou que o agente está olhando para uma branch diferente da sua:
- Análise ainda em execução ou ainda não disparada. Insights são gerados automaticamente após o backfill ser concluído. Como confirmar: a página de Insights mostra um banner de processamento enquanto o agente é executado; dê a um novo repositório alguns minutos.
- Branch de análise errada. A análise segue a branch de análise escolhida no modal de Monitoramento (a branch padrão do repositório por padrão); workflows que existem apenas em outras branches não são analisados. Como confirmar: abra o modal de Monitoramento e verifique o seletor de branch ao lado do repositório. Veja Gerenciando repositórios.
- Legitimamente pouco a dizer. Workflows pequenos ou raramente executados podem produzir poucas recomendações; isso é um achado, não uma falha. Editar um arquivo de workflow reaciona a análise, então volte a verificar após a sua próxima mudança de workflow.
Aplicar recomendações falhou ou descartou mudanças#
As recomendações são geradas com base no arquivo de workflow como ele existia no momento da análise. Se o arquivo mudou desde então (suas edições, ou um PR do Latchkey anteriormente mesclado), algumas recomendações deixam de se aplicar de forma limpa:
- O Latchkey abre o PR com o que ainda se encaixa e lista as recomendações que precisam de colocação manual. O PR chega com o título "latchkey AI: Optimize <workflow> workflow" em uma branch
latchkey/optimize-..., e um banner de sucesso leva você diretamente a ele. - Se todas as recomendações selecionadas foram descartadas, não tente novamente o conjunto desatualizado. Editar o workflow dispara uma nova análise; aguarde ela terminar (o banner de processamento na página de Insights desaparece), então aplique a partir do conjunto novo. Veja Insights de otimização.
Um pagamento falhou e o acesso está bloqueado#
Um status Past Due significa que um pagamento falhou: o acesso ao painel e à API é bloqueado e os lançamentos de runner param até que o método de pagamento seja corrigido no portal do Stripe, onde métodos de pagamento, faturas (com PDFs) e detalhes da assinatura são gerenciados. Se a assinatura foi Canceled em vez disso, o acesso é bloqueado mas a cobrança permanece acessível para que você possa reassinar. Seus dados são retidos em ambos os casos. Os status e seus efeitos estão listados em Gerenciando sua assinatura.
Não consigo usar o painel no meu celular#
Isso é intencional por enquanto: o painel é apenas para desktop, e navegadores de celular e tablet veem um aviso de bloqueio após o login. Notificações por email, Slack e push, além do resumo semanal, mantêm você informado longe da sua mesa.
Instalei o app na minha conta pessoal#
Contas pessoais não são suportadas. O Latchkey removeu automaticamente essa instalação, então não há nada para limpar; refaça o onboarding e escolha uma organização do GitHub. Se você só tem uma conta pessoal, crie uma organização primeiro (gratuito no GitHub) e mova seus repositórios para ela. Detalhes em Instale o GitHub App.
Meu trial encerrou e está tudo bloqueado#
Seus dados estão intactos; o bloqueio é no acesso, não no armazenamento. O painel é substituído por uma tela "Your free trial has ended", o acesso à API é bloqueado com a mesma mensagem, e os lançamentos de runner gerenciado são bloqueados (jobs direcionados a labels latchkey-* permanecem em fila no GitHub em vez de dar erro). Assine a partir da tela de ativação (ou do modal de Cobrança, se você conseguir alcançá-lo) e o acesso, incluindo os lançamentos de runner, é restaurado imediatamente. O trial roda uma vez por workspace, então assinar ou mudar de plano não o reinicia. Veja Planos e o trial gratuito.
Ainda travado?#
O FAQ cobre as respostas rápidas. Para qualquer outra coisa, vá para o Suporte ou use Send Feedback na barra lateral do painel; ambos chegam diretamente à equipe.