Deployment preso em queued: o que verificar primeiro

Um deployment preso em queued é uma das falhas menos informativas que uma plataforma pode apresentar. Nada caiu. Nenhum log apareceu, porque nada foi executado. O release simplesmente fica parado, e cada atualização mostra a mesma palavra.

A parte frustrante é que "queued" abrange pelo menos quatro situações diferentes, sem nenhuma relação entre si. Descobrir em qual delas você está leva cerca de trinta segundos e define se você deve esperar, tentar novamente ou investigar algo completamente diferente.

O que "queued" realmente significa

Um deployment em queued foi aceito e registrado, mas ainda não recebeu um worker. Entre esses dois momentos, algumas condições precisam ser atendidas:

• A plataforma precisa buscar seu código-fonte, o que geralmente significa fazer uma chamada de API ao seu provedor Git.
• Um slot de build precisa estar disponível.
• Qualquer pré-requisito do release precisa ter sido concluído — uma etapa de migration, uma operação de volume ou um deployment anterior do mesmo serviço.

Se qualquer uma dessas etapas estiver bloqueada, o registro existe, mas o trabalho não começa. Esse é todo o mecanismo. Não há mistério, mas a maioria dos dashboards exibe os quatro casos com a mesma palavra.

Os quatro casos, na ordem em que vale a pena verificar

1. Seu provedor Git está passando por problemas

Essa é a causa mais comum e aquela sobre a qual você não pode fazer nada. A plataforma solicitou seu repositório e recebeu uma resposta lenta ou um erro. Se vários serviços sem relação entre si entrarem em queued ao mesmo tempo e nenhum deles compartilhar código, a dependência comum é o provedor.

Consulte a página de status do seu provedor antes de qualquer outra coisa. Um deploy que está aguardando uma API upstream será liberado sozinho, e tentar novamente apenas adiciona outro registro à fila — por isso uma fila travada frequentemente se transforma em cinco filas travadas.

2. Algo à frente ainda não terminou

A maioria das plataformas serializa deployments por serviço, e com razão: dois builds gravando a mesma tag de imagem não são uma corrida que você queira vencer. Se um deployment anterior desse serviço ainda estiver em execução — ou, pior, ainda for considerado em execução porque um worker morreu sem informar — o próximo ficará aguardando.

No Dockup, dockup deployments lista o histórico começando pelo mais recente, com o status de cada entrada. Se o deployment acima do seu release em queued não estiver em um estado terminal, essa é a resposta: cancelá-lo ou deixá-lo atingir o timeout é o que libera a fila.

dockup deployments my-project/my-api --json

A saída --json inclui o status e a duração de cada deployment, tornando óbvio que "o anterior nunca terminou" de uma forma que um spinner não consegue mostrar.

3. Não há capacidade disponível

Toda plataforma tem um número finito de build workers. Em um tier compartilhado, um pico de atividade em toda a plataforma pode colocar você atrás dos builds de outras pessoas. Isso acontece de verdade, geralmente dura pouco e é o único caso em que esperar é realmente a decisão certa.

O que importa aqui é saber se você consegue ver isso. Uma posição na fila ou uma estimativa de espera transforma uma experiência que parece uma indisponibilidade em algo normal. Um simples "queued" não.

4. O deployment nunca chegaria a iniciar

O caso mais desagradável: o registro foi criado, mas aquilo que deveria processá-lo nunca o fez. Um worker caiu, um webhook foi perdido ou um token expirou entre o trigger e a busca do código.

O sinal é o tempo. As esperas em fila são medidas em segundos ou alguns minutos. Um deployment que está em queued há dez minutos, sem nenhum outro release à sua frente, não está esperando — está travado e continuará assim.

Como diferenciar uma espera de um travamento

Antes de tentar novamente, reúna três informações:

1. Há outro deployment em andamento? Se outro release do mesmo serviço estiver executando, você está no caso 2 e deve deixá-lo seguir.
2. Há quanto tempo ele está em queued? Menos de dois minutos é normal. Mais de dez, não.
3. Outros serviços entraram em queued ao mesmo tempo? Se serviços sem relação entre si pararam de uma vez, investigue a origem do problema, não o seu código.

Essas três respostas separam "esperar" de "agir" quase sempre.

Por que tentar novamente geralmente piora a situação

O impulso diante de um release travado é pressionar o botão de deploy novamente. Em um pipeline serializado, isso é contraproducente: você adiciona um segundo registro atrás do primeiro e, se o primeiro estiver realmente travado, o segundo herda o bloqueio. Desenvolvedores que passam por isso frequentemente acabam com uma coluna de entradas em queued, nenhuma das quais será executada até que o início da fila seja liberado.

Se você pretende tentar novamente, cancele primeiro o deployment travado. Um deployment em queued que falha de forma visível é muito mais útil do que cinco que ficam parados.

Como lidamos com isso no Dockup

A decisão de design mais importante aqui é que um deployment nunca fica considerado em execução indefinidamente. Cada um tem um estado terminal, e alcançá-lo é o que libera a fila. Um build que morre sem informar o resultado ainda atinge o timeout e libera o serviço.

Duas outras coisas ajudam mais do que pode parecer:

As etapas têm nomes. Um deployment do Dockup passa por busca do código-fonte, build e health gate, e cada etapa registra sua própria duração. Quando algo está lento, você consegue ver qual etapa está lenta em vez de observar uma única palavra. stageTimings está presente em todos os registros de deployment, inclusive por meio de --json.

Nada fica em fila atrás de um release que já falhou. Se o health check nunca passar, o deployment termina — ele não continua ocupando o serviço enquanto você espera sem saber o que está acontecendo. A versão anterior continua atendendo ao tráfego durante todo o tempo, que é a outra razão pela qual um release travado não representa uma indisponibilidade no Dockup.

# What is the current state, and how long has each stage taken?
dockup status my-project/my-api --json

# Follow the build as it happens rather than waiting for a summary
dockup logs my-project/my-api --build --follow

A regra geral

Estar em fila não é um modo de falha. Estar em fila sem um motivo associado é. Qualquer plataforma ocasionalmente fará você esperar por um provedor Git ou por um build slot; a diferença entre um incômodo de cinco minutos e uma tarde perdida está em a interface informar em qual dos quatro casos você se encontra.

Ao avaliar onde executar algo, vale a pena verificar isso de propósito: acione um deploy e observe o que a plataforma mostra entre aceitá-lo e iniciá-lo. Se a resposta for uma única palavra sem timestamp, em algum momento você perderá uma tarde com esse problema.

Perguntas frequentes

Por quanto tempo um deployment deve permanecer em queued? De alguns segundos a alguns minutos em uma plataforma saudável. Qualquer coisa além de dez minutos, sem nada à sua frente, deve ser tratada como travada, não apenas lenta.

Devo tentar novamente um deployment em queued? Não antes de cancelá-lo. Em um pipeline serializado, uma nova tentativa entra na fila atrás do deployment travado e herda o mesmo bloqueio.

Um deployment travado pode tirar meu site do ar? Não deveria. Em uma plataforma que só direciona o tráfego depois que um novo release passa pelo health check, a versão em execução continua atendendo durante todo o processo — um deploy em queued ou com falha é um release que nunca aconteceu, não uma indisponibilidade.

Por que vários serviços entram em queued ao mesmo tempo? Porque compartilham uma dependência, que quase sempre é o provedor Git ou a frota de builds, e não algo no seu código.