Solução de problemas

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.

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. Para saber como o provisionamento decide entre uma captação a quente e um início a frio quando nada está errado, veja Como funciona o provisionamento. Faça a triagem nesta ordem:

1. 01Label correto?Preset exato ou label personalizado, sem erros de digitação
2. 02Repo monitorado?Verifique o modal de Monitoramento
3. 03Config habilitada?Uma configuração desabilitada para de aceitar jobs
4. 04Cobrança OK?Estado de trial, assinatura e camada gratuita
5. 05Imagem pronta?Builds de runner personalizado levam tempo
6. 06No limite?Todo workspace começa com 40 jobs simultâneos, o número do plano Launch

O painel não mostra dados#

Um painel vazio quase sempre significa filtros ou tempo, não dados perdidos. Verifique nesta ordem:

1. Nenhum repositório selecionado. O Command & Control exibe os repositórios selecionados em seus Filters. Como confirmar: sem nenhum repositório selecionado, o seletor de workflows fica desativado e mostra "Select a repository first". Reset filters (Reset no Easy) seleciona de novo todos os repositórios e workflows e volta a janela Date range para os últimos 30 dias.
2. 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.
3. Nenhuma execução na janela. O backfill cobre execuções concluídas dos últimos 30 dias, e a janela Date range deve se sobrepor à atividade real. Como confirmar: as execuções de workflow recentes do repositório no GitHub mostram se a última execução é anterior à janela de backfill e, se for, as páginas permanecem vazias até que novas execuções ocorram. A janela padrão, os últimos 30 dias, coincide com a janela de backfill.
4. 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 insight: <what it does>" (por exemplo "Latchkey insight: pin GitHub Actions to commit SHAs") em uma branch latchkey/insight-<detector>-<hex>, 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 precisa de uma tela de tablet, laptop ou desktop, e uma tela mais estreita que 768 px mostra um aviso após o login com o título "A larger screen is needed". 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#

Essa instalação está conectada, e a conta executa o Latchkey CI nos repositórios que você registra pelo painel. Um job do GitHub Actions de um repositório registrado direcionado a um label latchkey-* não roda em um runner do Latchkey, e o Latchkey diz por quê: "Latchkey on GH needs a GitHub organization. This personal account runs Latchkey CI: commit a workflow file under .latchkey/workflows/ and push." Arquivos de workflow descreve o arquivo. Para usar o Latchkey on GH (os runners gerenciados do Latchkey no GitHub Actions) com um repositório em uma conta pessoal, mova-o para uma organização como mostra 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 da página Billing, se você conseguir alcançá-la) e o acesso, incluindo os lançamentos de runner, é restaurado imediatamente. Há um trial gratuito por pessoa, e assinar ou mudar de plano não o reinicia. Veja Planos e o trial gratuito.

O que significa o failure_reason de um job#

Quando o próprio Latchkey encerra um job do Latchkey CI, em vez de o seu comando decidir o resultado, o failure_reason do job é um dos valores abaixo. Cada valor é a palavra exata que o Latchkey registra, por isso não é traduzido.

Falhas do próprio Latchkey#

Cancelamentos feitos por você#

Conexão e registro#

Cobrança e elegibilidade#

A sua própria entrada#

Dois tipos de failure_reason são abertos, então nenhuma tabela consegue listá-los. O primeiro é um motivo que o próprio job reportou: o Latchkey o mostra como as palavras do próprio job, e o check Latchkey fica vermelho. Um deles, context_fetch_failed, significa que o job não conseguiu buscar o contexto que o Latchkey guardava para ele. Quando o Latchkey confirma a falha como sua (o contexto que ele guardava está ausente), o check fica neutro e a linha e a CLI dizem isso; quando não consegue, o check continua vermelho, com as palavras do próprio job. Outro deles, service <label> could not start, é uma falha do Latchkey quando o próprio runner falhou ao iniciar o serviço (a escrita do nome de host, o mecanismo de containers sem responder ou recusando o início, ou o cliente desse mecanismo não preparado) e do seu job quando o rótulo já é um nome de host no runner, ou quando a imagem não pôde ser baixada, parou ou não ficou pronta a tempo; o log do job diz qual é o caso, com as próprias palavras do registry quando um download é recusado, e no caso do Latchkey o check fica vermelho mesmo assim até que o Latchkey consiga confirmar essa falha por conta própria. O Latchkey verifica o runner antes que um job com serviços comece e, quando essa verificação prova que o runner não consegue rodá-los (o cliente do mecanismo de containers não pode ser preparado, o mecanismo recusa criar uma rede, falta o privilégio de escrever nomes de host ou, em um runner com início a frio para o job, o mecanismo não responde), o job passa para outro runner em vez disso. Um job que esgota as tentativas dessa forma termina com refused: runner_cannot_prepare_services da primeira tabela, e o check não fica vermelho. O segundo é launch_failed: seguido do nome de um erro: o Latchkey não conseguiu iniciar um runner para o job, o que é uma falha do Latchkey como as da primeira tabela, e é seguro tentar novamente.

Ainda travado?#

O FAQ cobre as respostas rápidas. Para qualquer outra coisa, o Suporte e Send feedback no menu Account and help chegam diretamente à equipe.