Versionamento
Snapshots imutáveis, um ambiente de desenvolvimento fisicamente separado da produção e rollback em segundos. É o modelo de release do browserMate.
Conceito de versão
Cada processo pode ter múltiplas versões. Uma versão é um snapshot completo e imutável do processo em um ponto no tempo, incluindo todas as etapas, mapeamentos, configurações e instâncias de conectores. Uma vez publicada, uma versão nunca é sobrescrita: uma nova rodada de edição sempre gera a próxima versão numerada e jamais altera as anteriores.
As versões permitem:
- Desenvolver com segurança: edite num ambiente isolado, sem arriscar a versão em produção
- Rollback rápido: se uma versão nova quebrar em produção, restaure a anterior em segundos
- Auditoria: veja o estado exato do processo em qualquer release passado, com autor e data
Dev × Produção: bases fisicamente separadas
Isto é o que torna o versionamento seguro para times inteiros, e não só para quem está editando: desenvolvimento e produção não são apenas um rótulo, são duas bases de dados distintas. Ao abrir uma versão para edição, o browserMate copia o snapshot atual do processo para uma base de desenvolvimento isolada e todo o trabalho acontece ali. A base de produção, de onde as execuções normais leem, permanece intocada até que a nova versão seja explicitamente publicada.
| Desenvolvimento | Produção (Release) | |
|---|---|---|
| O que é | A versão aberta para edição no Agent Builder | A última versão publicada do agente |
| Onde os dados vivem | Base de desenvolvimento isolada, uma cópia de trabalho separada fisicamente | Base de produção, a fonte usada por qualquer execução normal |
| Quem executa | Execuções de Debug feitas pelo desenvolvedor no builder | Execuções normais: RUN do card, Agendamento e API |
| Quem edita | Só quem abriu a versão (o desenvolvedor com o bloqueio) | Ninguém. Produção não é editada diretamente, só recebe releases |
O editor em somente leitura
O botão EDIT do card nunca fica desabilitado. Quando não existe uma versão em desenvolvimento aberta, o Agent Builder abre assim mesmo, só que exibindo a versão publicada em modo de consulta. Uma faixa no topo diz exatamente isso, como na imagem abaixo:
O texto do lado direito da faixa muda conforme o motivo do bloqueio:
| O que a faixa diz | Significado |
|---|---|
| crie uma nova versão para editar | O processo está liberado. Você pode abrir uma versão de desenvolvimento agora mesmo. |
| em desenvolvimento por Fulano | Outra pessoa detém o bloqueio. Só ela edita até publicar ou cancelar. |
| você não tem permissão de edição neste processo | O agente foi compartilhado com você sem a permissão edit. Veja Compartilhamento. |
Nesse modo, tudo que grava desaparece da tela: criar e mover etapas, salvar, reordenar, excluir, o Debug e o Copilot. O que continua disponível é a leitura do fluxo, a navegação pelo canvas e a consulta ao que está publicado: o painel da etapa (Propriedades, Objetos e Mapeamentos) e as Configurações do Agente abrem com os campos travados e sem o botão de salvar, mostrando a versão em produção. Dá para conferir código, regra de rota, variáveis e parâmetros sem abrir uma versão.
Criar uma nova versão
Com o editor aberto em somente leitura, o botão Desenvolver versão X aparece na primeira fileira do cabeçalho, ao lado da versão que está em produção. O X é o número da versão que será criada. É a única ação de escrita disponível nesse estado.
Esse número é sempre o da versão seguinte à última que já foi publicada, e não necessariamente o seguinte à versão em produção. Se você definiu uma versão anterior como a corrente, o botão continua mostrando a próxima do histórico.
- Clique em Desenvolver versão e confirme.
- O snapshot atual é copiado para a base de desenvolvimento e o processo fica bloqueado para você. O card na tela Meus Agentes de Processo passa a mostrar quem detém o bloqueio.
- A faixa de somente leitura some, os controles de edição voltam e o editor passa a trabalhar sobre a versão nova.
Enquanto a versão está aberta, o card do agente mostra o estado para todo mundo: a versão em Desenvolvimento, quem detém o bloqueio e, com o processo travado, o botão de excluir indisponível.
Pendências: o que segura a publicação
Na segunda fileira do cabeçalho existe um indicador de pendências. Ele é a checagem que o builder faz continuamente para responder a uma pergunta: este agente está pronto para rodar? Clique nele para abrir a lista do que ainda falta.
Enquanto houver qualquer pendência aberta, o botão de publicar não aparece. Não é um defeito, é proposital: não faz sentido lançar em produção um modelo incompleto.
Ao publicar, a plataforma confere de novo no servidor as pendências de runtime, ambiente e agendamento, venha a publicação de onde vier, e recusa com o motivo num aviso no editor. Os casos e as mensagens estão em Runtimes e Ambientes → Ambientes.
| Pendência | Como resolver |
|---|---|
| Crie sua primeira etapa | O fluxo ainda não tem nenhuma etapa. Clique no card + do canvas e escolha o tipo da primeira. |
| Etapas sem configuração | Abra cada etapa listada e complete a configuração que falta. |
| Runtime: nenhum runtime selecionado para este agente | Escolha um runtime no campo RUNTIME. |
| Ambiente: o runtime não tem instalação no ambiente do agente | O runtime escolhido não tem instalação no ambiente em que o agente está (Desenvolvimento, Homologação ou Produção), por exemplo O runtime X não tem instalação em Y. Escolha outro runtime no campo RUNTIME, troque o ambiente pelos botões Dev, Homolog e Prod ao lado dele, ou edite o runtime e dê uma instalação a esse ambiente. Com a instalação desse ambiente suspensa pelo plano, a pendência diz A instalação NOME (Ambiente) está suspensa pelo plano: faça upgrade do plano, ou escolha outro runtime. Quando o runtime foi removido, a pendência diz O runtime gravado neste agente não existe mais na sua conta. Escolha outro.: o campo RUNTIME fica em Selecione..., os botões de ambiente ficam desabilitados, e a correção é escolher outro runtime. Veja Runtimes e Ambientes → Ambientes. |
| Agendamento: agendamento aponta para um runtime sem instalação no ambiente do agente | Um agendamento ligado deste agente fixa um runtime que não tem instalação no ambiente do agente, por exemplo O agendamento "D" aponta para o runtime X, sem instalação em Y. Cada disparo dele seria recusado. Troque o runtime do agendamento em Agendamento, ou dê ao runtime uma instalação nesse ambiente. Agendamento desligado não entra nesta pendência. |
| Cofre de Senhas: chave sem valor para o ambiente do agente | Uma credencial usada no fluxo não tem valor para o ambiente em que o agente está. Abra o painel do Cofre, aba Neste fluxo, e preencha o valor daquele ambiente. Veja Cofre de Senhas → Valores por ambiente. |
| Modelo precisa ser salvo | Clique em Salvar para gravar as alterações pendentes do canvas. |
| Mapeamento de webhook não salvo | Abra o modal de Webhook e salve o mapeamento em aberto. |
| Script com erro de sintaxe | Abra a etapa listada: o editor sublinha a linha com o problema e descreve o que houve. Veja Código Inline: Erros de sintaxe. |
Publicar ou cancelar a versão
Resolvidas as pendências, dois botões ficam disponíveis no canto direito da primeira fileira do cabeçalho, ao lado do nome do processo:
- Publicar versão X: confirma e pede uma descrição do release. Se você deixar em branco, ela é salva como "Otimização do Processo". O conteúdo da base de desenvolvimento vira a nova versão numerada e a release ativa, o bloqueio é liberado e a cópia de desenvolvimento é apagada.
- Cancelar versão: descarta tudo que foi editado na base de desenvolvimento e libera o bloqueio. A produção nunca chega a ver essas mudanças.
As versões publicadas são exibidas no formato 1.0, 2.0 e assim por diante, cada uma com o rótulo descrito na publicação.
Selecionar uma versão anterior (rollback)
Enquanto o processo não está bloqueado, ou seja, quando não há versão em desenvolvimento aberta, o seletor de versão na aba Profile do card lista todos os releases já publicados, do mais recente para o mais antigo. Escolher uma versão diferente da atual não é uma "prévia": é a ativação imediata, com um pedido de confirmação. O conteúdo daquela versão volta a ser a release corrente na hora, sem precisar reabrir nada no modelador.
- No seletor de versão do card, escolha a versão anterior que estava funcionando.
- Confirme a publicação. A partir daí, todas as execuções (RUN, agendamento, API) passam a usar essa versão.
- A versão problemática continua guardada no histórico e nada é apagado. Basta selecioná-la de novo depois de corrigida.
O que é versionado
Cada versão contém um snapshot completo de:
| Elemento | Incluído na versão |
|---|---|
| Etapas | ✅ Todas as etapas com suas configurações completas |
| Mapeamentos de dados | ✅ Configurações de captura e transformação |
| Rotas e condições | ✅ Toda a lógica de decisão |
| Configurações do agente | ✅ Nome, avatar, browser, limites, notificações |
| Instâncias de conectores | ✅ Qual conector e qual ação cada etapa usa |
| Projetos de código referenciados | ✅ Referência ao projeto, não o arquivo em si |
| Credenciais do Cofre | ❌ Não versionadas. São gerenciadas separadamente |
| Credenciais de conectores | ❌ Não versionadas. Sempre usa a credencial atual |
| Histórico de execuções | ❌ Não está vinculado à versão |
Boas práticas
- Descreva o release ao publicar. "Novo tratamento de erro 404" te diz muito mais, seis meses depois, do que aceitar o texto padrão.
- Não deixe a versão de desenvolvimento aberta por dias. Enquanto ela existe, o processo fica bloqueado para todo mundo. Publique ou cancele assim que possível, especialmente em processos compartilhados.
- Teste no Debug antes de publicar. As execuções de Debug rodam contra a base de desenvolvimento e são a chance de validar antes que a mudança vire release.
- Resolva as pendências cedo. O indicador fica verde quando o agente está pronto. Deixar para conferir na hora de publicar costuma revelar etapa incompleta no pior momento.
- Versões antigas ficam para sempre. Não existe exclusão seletiva de versão. Todo o histórico de releases permanece disponível para rollback e auditoria, sem risco de alguém apagar por engano.
- Use versões para desenvolvimento paralelo. Enquanto a versão 3 está em produção, a versão 4 pode ser editada na base de desenvolvimento sem afetar as execuções em andamento.