Antes de começar
Você precisa de uma conta na Guarita e de permissão pra instalar integrações na conta (ou no time) da Vercel que é dona dos projetos.
- Permissão na Vercel — poder instalar integrações na conta pessoal ou no time certo.
- Autorização pra testar — só autorize apps que são seus ou que você tem permissão pra avaliar.
- Site no ar — a primeira ronda só começa quando existe um endereço público em produção.
Instalar a integração
Do Marketplace da Vercel até a primeira ronda, em cinco passos.
- 01Abra a Guarita a partir do Marketplace da Vercel ou das configurações de integração da Guarita.
- 02Escolha a conta pessoal ou o time e libere o acesso a todos os projetos ou só aos selecionados.
- 03Entre na Guarita. Login, cadastro, verificação de e-mail, recuperação de senha e 2FA preservam o fluxo de instalação — você não perde o caminho.
- 04Revise a lista exata de projetos, marque o que quer proteger e confirme que você tem autorização pra testar esses apps.
- 05Ative a proteção. A Guarita verifica que o projeto é seu e só inicia a primeira ronda quando existe um endereço público válido.
Permissões usadas
A Guarita pede só os recursos da Vercel necessários pra manter a instalação, descobrir os projetos e rodar rondas cientes de cada publicação (deploy).
| Recurso | Acesso | Por quê |
|---|---|---|
| Integration Configuration | Leitura / Escrita | Validar a instalação e removê-la primeiro na Vercel quando você desconectar. |
| Projects | Leitura | Listar os projetos autorizados e descobrir os endereços públicos verificados. |
| Deployments | Leitura | Identificar quando uma versão entra em produção e qual é o endereço exato dela. |
| Deployment Checks | Leitura / Escrita | Devolver o resultado da ronda pra dentro da Vercel — e, se você ligar, segurar a publicação. É o único recurso opcional da lista. |
A integração base não pede acesso a variáveis de ambiente, cobrança, domínios, times, drains nem configuração global. Deployment Checks é o recurso progressivo: sem ele a Guarita protege o app e o resultado fica no painel da Guarita; com ele, o resultado também aparece na Vercel. Se a instalação não concedeu esse acesso com escrita, a tela do projeto diz isso e oferece “Autorizar na Vercel”.
Verificação do projeto e a primeira ronda
A instalação na Vercel é a prova, dada pelo próprio provedor, de que o projeto selecionado está sob o seu controle. Ela substitui a verificação manual por DNS ou arquivo pra esse projeto.
Verificação
A Guarita guarda essa prova (revogável a qualquer momento) e a reconfere periodicamente com a Vercel. Ela nunca inventa um endereço *.vercel.app por conta própria.
Primeira ronda
Uma ronda só roda contra um endereço exato e válido informado pela Vercel. Se ainda não existe um endereço público acessível, o projeto continua verificado — só esperando o site entrar no ar.
Ronda a cada publicação em produção
Nos planos Pro e Business, cada vez que uma nova versão do site vira a oficial em produção, a Guarita pode iniciar uma nova ronda autorizada no projeto ativo.
Nova versão em produção
A Guarita recebe o evento assinado da Vercel e identifica a publicação exata.
Ronda autorizada
A autorização do projeto e o endereço são revalidados antes de qualquer tráfego sair.
Resultado claro
O relatório mostra se a versão está estável, piorou, foi bloqueada ou ficou incompleta.
Essa automação é opcional e pode ser desligada projeto a projeto. Ela reage só quando uma versão entra em produção — não a cada preview.
Resultado no deploy
Com o escopo de Deployment Checks concedido, a tela do projeto na Guarita ganha dois interruptores. Os dois nascem desligados e ligar qualquer um deles exige plano Pro ou Business — é a mesma capacidade que libera a ronda a cada publicação.
| Interruptor | O que faz | Requisitos |
|---|---|---|
| Mostrar resultado na Vercel | Publica o resumo da ronda junto do deploy, como um Check chamado “Guarita Security”. Começa em modo informativo: aparece, não segura nada. | Pro / Business |
| Segurar regressões graves | Torna o Check bloqueante. Ele reprova a publicação só quando aparece brecha ALTA ou CRÍTICA que não existia na ronda anterior e que a ronda já dá como certa — no relatório, ela vem com o selo “✓ confirmado” ou sem selo de confiança nenhum. Achado com o selo “a confirmar” (pista forte, ainda não provada) nunca derruba deploy, e a primeira ronda nunca reprova — ela vira o baseline. | Pro / Business, com o de cima ligado |
O bloqueio falha para o lado seguro: se a ronda não terminar em 4 minutos, o Check é encerrado como ignorado e a publicação segue — a ronda continua em segundo plano e o resultado chega no painel. Segurança não é motivo para travar a sua fila de deploy.
Acessar previews protegidos
Se um preview (a versão de teste do seu site) usa o Deployment Protection da Vercel, você pode informar o segredo de Automation Bypass — a chave de visita que a própria Vercel gera — nas configurações do projeto na Guarita.
- O segredo fica criptografado e nunca volta pro navegador depois de salvo.
- Ele só é usado pelo nosso serviço no momento em que uma ronda autorizada começa.
- A credencial vale só pro endereço exato do preview e é revogada ao desativar ou desconectar.
Gerenciar, pausar ou desconectar
Abra Configurações → Integrações na Guarita, ou use a Configuration URL disponível no painel da Vercel.
Sincronizar acesso
Atualiza projetos, domínios, status da instalação e a prova de controle.
Pausar um projeto
Interrompe as próximas rondas e revoga a autorização ativa daquele projeto.
Desconectar
Remove a configuração primeiro na Vercel e depois revoga a prova local e o acesso aos previews.
Desconectar interrompe qualquer atividade futura ligada à Vercel e descarta as credenciais OAuth e de preview. O histórico de rondas existente continua seguindo o período de retenção do seu plano.
Resolvendo problemas
Nenhum projeto aparece na lista
Confirme que a instalação na Vercel tem acesso a pelo menos um projeto. Se você liberou só projetos selecionados, adicione o projeto na Vercel e use Sincronizar na Guarita.
O projeto está verificado, mas nenhuma ronda começou
A instalação provou que o projeto é seu, mas a Vercel ainda não informou um endereço público acessível em produção. Publique o projeto (ou promova uma versão pra produção) e depois sincronize ou rode a ronda do projeto.
Um preview protegido está bloqueado
Crie (ou gere de novo) o segredo de Automation Bypass na Vercel, salve nas configurações do projeto na Guarita e use “Rodar e testar acesso”.
A conexão aparece desativada
Revise a instalação e as permissões na Vercel e então reconecte ou sincronize. Quando não consegue confirmar a permissão do provedor, a Guarita prefere parar a arriscar — é uma trava de segurança.
Um projeto foi removido ou transferido
A Guarita revoga a prova de controle dele. Reinstale ou autorize o projeto de novo na conta que agora controla o projeto.
A tela diz que falta permissão pra devolver resultado à Vercel
A instalação foi feita sem o escopo de Deployment Checks com escrita. O app segue protegido e o resultado continua no painel da Guarita; pra ver o Check dentro da Vercel, use “Autorizar na Vercel” na tela do projeto e conceda o recurso.
Liguei “Segurar regressões graves” e o deploy passou mesmo assim
Três motivos legítimos: era a primeira ronda daquele projeto (ela vira o baseline e nunca reprova); as brechas encontradas não eram altas ou críticas já dadas como certas — o que o relatório marca com o selo “a confirmar” não derruba deploy; ou a ronda passou de 4 minutos e o Check foi encerrado como ignorado pra não travar a sua fila.
Dados e segurança
A Guarita lê apenas as informações de projeto e publicação necessárias pra operar a integração autorizada.
A Guarita usa
- • Identificadores da instalação, da conta/time e dos projetos selecionados
- • Nomes dos projetos e os endereços exatos verificados
- • Identificadores de publicação, ambientes, URLs e eventos de produção
- • Credenciais OAuth e de acesso a preview, sempre criptografadas
A Guarita não
- • Altera código-fonte, domínios ou variáveis de ambiente
- • Inventa um endereço a partir do nome (mutável) do projeto
- • Ronda um projeto não selecionado sem autorização explícita
- • Expõe credenciais OAuth ou de preview no navegador
Ainda travado?
Mande o nome do projeto, o ID da configuração, o horário aproximado e o erro exato. Nunca envie token OAuth nem o segredo de Automation Bypass.