Skip to main content

Command Palette

Search for a command to run...

Agentes na nuvem

Rollouts

O Rollouts monitora cada pull request, da revisão até a produção. Ele cria um plano de liberação quando o pull request é aberto, verifica a alteração com base na sua telemetria após o deploy e relata a integridade dela em cada ambiente.

Configure o Rollouts em Automações.

Como funciona

Planos de liberação

Quando um pull request é aberto, o Rollouts analisa o diff e os sistemas afetados por ele e, em seguida, gera um plano de liberação. O plano lista os riscos encontrados pelo Rollouts, o efeito esperado da alteração, os sinais que ele vai verificar e eventuais lacunas de instrumentação que dificultariam a verificação da alteração. No GitHub, no GitLab.com e no Bitbucket Cloud, o Rollouts publica o plano como comentário no pull request. No Origin, o plano aparece na página da Pull Request.

Para alterar o plano, mencione o handle indicado no comentário do Rollouts em um comentário de pull request e diga o que deve ser monitorado ou ignorado. O Rollouts revisa o plano e responde. Somente pessoas com acesso de gravação ao repositório podem alterar o plano.

Rastreamento de deploys

O Rollouts é acionado por eventos de deploy do commit da alteração e executa o plano com base nos seus logs, métricas e traces. Ele rastreia cada ambiente separadamente, então uma alteração pode ser verificada em staging e, mesmo assim, ser sinalizada em produção.

O Rollouts verifica um deploy assim que ele acontece e depois de novo após 20 minutos, 1 hora, 1 dia e 3 dias.

Se uma alteração mergeada entrar no ar sem um deployment registrado, selecione Run checks na página da alteração. O botão fica à direita das abas de ambiente e aparece sozinho nessa linha enquanto a alteração ainda não tiver verificações. Escolha o ambiente e os serviços e inicie as verificações. O Rollouts passa a considerar a versão da alteração como ativa nesse ambiente e a verifica seguindo o mesmo agendamento.

Regressões

Quando o Rollouts detecta uma regressão, ele aponta a alteração suspeita, abre uma issue e notifica o autor. Ele faz o mesmo quando uma alteração não causa regressão, mas não funciona como esperado: o novo caminho de código foi executado, mas não produziu o efeito esperado, gerou erros ou teve um comportamento incorreto. Na página da issue, selecione Fix issue para iniciar um agente em nuvem nela ou Close para fechá-la. Ao fechar, é preciso informar um motivo (Fixed, Not a Real Issue, Expected, Duplicate ou Other) e um comentário, e ambos ficam registrados no histórico da issue. O agente é aberto em um painel na página da issue. Depois que uma correção é iniciada, View fix aparece no lugar de Fix issue e reabre esse agente. O Rollouts não mergeia, não desfaz nem reverte alterações por conta própria.

Rastrear alterações

A página Rollouts lista os pull requests mergeados e os agrupa em Attention, Monitoring, Pending e Verified. Mine lista as alterações em que você está inscrito, e Team lista todas as alterações da equipe. Os administradores da equipe veem Team por padrão, e os demais usuários veem Mine. Cada ambiente em que uma alteração recebe deploy exibe o próprio status, como Deploying, Monitoring, Verified, Deploy failed ou Issues found.

Uma alteração fica em Attention enquanto tiver uma issue aberta ou um deploy com falha. Quando todas as issues da alteração são fechadas, ela passa a ser considerada Verified. Se uma issue for reaberta, a alteração volta para Attention.

Serviços

Selecione Services na parte superior da página Rollouts para ver todos os serviços relatados pelo seu pipeline de deployment. Para ocultar um serviço dessa lista, abra-o e selecione Archive. Os deployments dele continuam no histórico. O serviço passa para Archived, onde você pode restaurá-lo com Restore.

Configurar Rollouts

Em Automações, abra a aba Team e selecione Enable no card Rollouts, em From Cursor. A configuração tem quatro etapas:

1

Acesso aos repositórios monitorados

Escolha os repositórios a serem monitorados. Cada pull request entregue a partir desses repositórios ganha seu próprio monitoramento, vinculado ao autor. O Rollouts monitora repositórios no Origin, GitHub, GitLab.com e Bitbucket Cloud.

2

Enviar eventos de deployment para o Rollouts

Informe ao Rollouts quando cada deployment em produção começa e termina. Crie uma chave de API e armazene-a como o segredo de CI CURSOR_API_KEY. Use uma chave de API de usuário, uma chave de API de conta de serviço ou uma chave da API de administração da equipe com o escopo admin:*. Você pode fazer isso manualmente ou com um agente. Nesse caso, um agente de configuração abre um pull request que adiciona as chamadas; depois, é só fazer o merge para concluir a configuração.

3

Telemetria

Conecte suas ferramentas de observabilidade, como o Datadog, para que cada alteração seja verificada com base no que está acontecendo em produção. O Rollouts precisa de pelo menos uma ferramenta conectada. Sem ela, as alterações ficam pendentes e o Rollouts não consegue detectar problemas.

4

Notificações

Escolha como os autores de pull requests serão notificados sobre suas liberações.

Enviar eventos de deploy

1

Trocar a chave de API por um token

No início do job de deploy, troque o segredo CURSOR_API_KEY por um token. Todas as chamadas abaixo enviam esse token.

TOKEN=$(curl -s -X POST https://api2.cursor.sh/auth/exchange_user_api_key \  -H "Authorization: Bearer $CURSOR_API_KEY" -H "Content-Type: application/json" -d '{}' \  | jq -r .accessToken)
2

Criar cada ambiente e serviço uma única vez

Execute isto manualmente ou como uma etapa de bootstrap antes do job de deploy. Isso cria os registros referenciados pelas chamadas abaixo, então execute-o antes do primeiro relato.

curl -s -X POST https://api.cursor.com/factory.v1.DeploymentsService/CreateEnvironment -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "Connect-Protocol-Version: 1" \  -d '{"environmentId":"{env}","environment":{"displayName":"{env}"}}'curl -s -X POST https://api.cursor.com/factory.v1.DeploymentsService/CreateService -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "Connect-Protocol-Version: 1" \  -d '{"serviceId":"{service}","service":{"displayName":"{service}"}}'
3

Criar o deployment

Execute isto logo antes de fazer o deploy. deployVersion é o SHA do commit que está sendo entregue.

DEPLOYMENT=$(curl -s -X POST https://api.cursor.com/factory.v1.DeploymentsService/CreateDeployment -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "Connect-Protocol-Version: 1" \  -d '{"deployment":{"deploySourceUri":"https://github.com/{owner}/{repo}","environment":"environments/{env}","service":"services/{service}","deployVersion":"'"$GIT_SHA"'"},"event":{"started":{},"actor":"'"$CI_JOB_URL"'"}}' \  | jq -r .deployment.name)
4

Adicionar o evento de conclusão

Execute isto assim que o resultado for conhecido. Uma falha no relato nunca deve fazer o deploy falhar.

curl -s -X POST https://api.cursor.com/factory.v1.DeploymentsService/AppendDeploymentEvent -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "Connect-Protocol-Version: 1" \  -d '{"name":"'"$DEPLOYMENT"'","event":{"completed":{"succeeded":{}},"actor":"'"$CI_JOB_URL"'"}}'# Em caso de falha: "event":{"completed":{"failed":{"message":"<why>"}},"actor":...}# Se cancelado:     "event":{"aborted":{},"actor":...}

Configurações

As configurações do Rollouts têm quatro seções:

  • Acesso ao código. Os repositórios que o Rollouts acompanha (até 200) e quais alterações monitorar.
  • Eventos de deployment. Como seu pipeline informa o que foi implantado e onde.
  • Fontes de dados. As conexões MCP que o Rollouts consulta para verificar as alterações implantadas e detectar regressões.
  • Notificações. Como você é avisado sobre deployments e regressões nas suas alterações.

A chave no topo das Configurações ativa ou desativa o Rollouts para sua equipe. O rótulo da chave exibe Habilitado ou Desabilitado. Somente administradores da equipe podem ativar ou desativar o Rollouts e configurar eventos de deployment. Os demais membros veem esses controles, mas não podem alterá-los.

Escolha quais alterações monitorar

Em Which changes to monitor, descreva em linguagem natural quais pull requests o Rollouts deve ignorar. Por padrão, o Rollouts ignora alterações que não afetam o que é executado em um ambiente implantado: alterações apenas na documentação, correções de formatação, lint ou erros de digitação sem alteração de comportamento, e alterações apenas em testes. Apague o texto para monitorar todas as alterações nos repositórios observados.

Um pull request só é ignorado quando se encaixa claramente nos critérios. Quando o Rollouts ignora um pull request, ele explica o motivo em um comentário. Para monitorá-lo mesmo assim, mencione o handle indicado no comentário.

Notificações

Ative Personal Slack Notifications para receber notificações sobre suas alterações no Slack. Por padrão, só são enviadas mensagens de Issues found. Para ser avisado também quando um deployment for bem-sucedido ou falhar, ou quando uma verificação não encontrar issues, ative Deployment succeeded, Deployment failed ou Check clear. Em Deliver to, escolha Direct message ou Channel. Para enviar a um canal, informe o nome ou o ID de um canal público, convide cada app listado abaixo do campo e salve. Canais do Slack Connect não são compatíveis.

Antes, um Admin da equipe precisa adicionar o Rollouts ao Slack. Somente Admins da equipe podem alterar os valores padrão de notificação da equipe. Com o padrão da equipe ativado, os membros recebem uma mensagem no Slack quando uma verificação encontra issues no pull request deles, até que alterem as próprias configurações. As notificações do Slack não ficam disponíveis no Privacy Mode.

Páginas relacionadas