Deploys canary e janelas de deploy

Esses são os controles para quando e como uma versão vai ao ar. Todos estão na página da aplicação e na API; a maioria também está na CLI.

Deploys canary

Um deploy padrão move todo o tráfego para a nova versão assim que ela passa pela verificação de integridade. Um deploy canary roda a nova versão ao lado da atual e envia só parte do tráfego para ela primeiro.

Para ativar: aplicação → Configurações → Geral → Estratégia de deploy. Escolha Canary e configure:

• Porcentagem do canary (%): de 1 a 99. Essa fração dos novos visitantes recebe a versão nova. Um cookie mantém cada visitante na versão que recebeu primeiro, por um dia.
• Etapas de ramp (%): uma lista opcional e crescente, por exemplo 5, 25, 50. Cada etapa roda como seu próprio canary, com o mesmo rollback automático descrito abaixo; quando a última etapa é concluída, promover manda tudo para 100%. Deixe em branco para uma única etapa e promova manualmente depois.
• Tempo por etapa (minutos): deixe em branco para promover cada etapa manualmente. Caso contrário, o Railyard avança para a próxima etapa, ou promove a última, automaticamente depois desse tempo.
• Reverter acima de uma taxa de erros 5xx (%): se a taxa de erros de uma etapa passar desse valor, o Railyard faz o rollback dela.

Enquanto um canary está no ar, a página da aplicação mostra um aviso. A página do deploy compara as requisições, a taxa de 5xx e a latência p95 do canary com o resto da aplicação, e tem os botões Promover (envia 100% para a versão nova, ou inicia a próxima etapa do ramp) e Reverter.

Vale saber:

• O comando de release, como suas migrations, roda antes do canary começar, então as migrations precisam funcionar com as duas versões.
• Workers e qualquer servidor extra continuam na versão atual até você promover.
• O primeiro deploy de uma aplicação, um deploy durante o modo de manutenção, uma aplicação só com worker e uma aplicação com volume de dados sempre usam um deploy padrão.

API: PATCH /api/applications/:id/deploy_strategy (deploy_strategy, canary_percent, canary_steps_text — separado por vírgulas, por exemplo "5, 25, 50" — canary_promote_after_minutes, canary_max_error_rate), depois POST /api/deploys/:id/canary/promote ou DELETE /api/deploys/:id/canary. Ainda não existe comando de CLI para canary.

Janelas de deploy

Uma janela de deploy define os dias, horários e fuso em que uma aplicação pode fazer deploy. Configure em Configurações → Geral → Janela de deploy.

• Pushes e deploys automáticos fora da janela esperam e saem como um único deploy quando a janela abre.
• Um deploy manual fora da janela pede confirmação antes, mas você pode seguir mesmo assim.
• Um rollback fora da janela é feito do mesmo jeito, com um aviso na tela de confirmação.
• Uma janela que termina antes de começar roda durante a noite (22:00–02:00). Desmarque todos os dias para permitir deploys em qualquer horário.

railyard deploy-window my-app mon,tue,wed,thu,fri 09:00 17:00 America/Toronto
railyard deploy-window my-app off
railyard deploy my-app --anyway          # fora da janela

API: PATCH /api/applications/:id/deploy_window com days, start, end e time_zone. "days": [] remove a janela.

Deploys agendados

Escolha um horário e o deploy começa nesse momento. O horário precisa estar dentro da janela de deploy, se a aplicação tiver uma. Você pode cancelar um deploy agendado, na fila ou em execução.

railyard deploy my-app --at 2026-10-02T14:00:00Z --message "pricing page"
railyard deploy:cancel 482

API: POST /api/applications/:id/deploys com at (ISO 8601), e POST /api/deploys/:id/cancel.

Notas de deploy

Adicione uma nota de até 500 caracteres a um deploy manual ou a um rollback. Ela aparece nas listas de deploys, na página do deploy, no log de atividade, nas notificações e nos webhooks deploy.*. Um deploy refeito mantém a nota.

railyard deploy my-app --message "hotfix for checkout"

O rollback recupera as variáveis

Fazer rollback refaz o deploy do commit (ou imagem) de uma versão anterior e recupera as variáveis com que ela rodava. A tela de confirmação lista as variáveis que voltam ao valor antigo e avisa se algum secret mudou desde então. Para reverter o código mantendo as variáveis de hoje:

railyard rollback my-app 471 --code-only --message "roll back, keep new keys"

Versões publicadas antes de o Railyard começar a guardar uma cópia das variáveis só conseguem reverter o código.

Fazer deploy de uma branch, tag ou commit uma única vez

Opções de deploy… na página da aplicação, railyard deploy my-app --ref v2.1.0, ou ref na API fazem deploy de outra branch, tag ou commit uma única vez. A branch que a aplicação acompanha não muda.

Pushes estritos no git

Com git push railyard main (veja CLI), o push espera o build terminar por padrão. Um build que falha rejeita o push, então a branch mantém seu commit antigo. Desative isso em Configurações → Geral ou com railyard git:strict my-app off.