Workspace Forks permite clonar um workspace em um filho, manter os dois ligados e mover mudanças de workflow deployadas entre eles depois. Pense em Deploy como um git commit: só o que você deployou é o que Forks pode copiar ou sincronizar. Sync é sempre um force push ou force pull — o lado alvo é sobrescrito para os workflows no sync. Não há UI de merge.
Um workspace tem no máximo um pai. Um pai pode ter muitos filhos. Você só pode sincronizar ao longo de uma aresta direta pai↔filho — não com um avô ou irmão.
Quem pode usar Forks
| Requisito | Detalhe |
|---|---|
| Plan | Enterprise no Zoen Cloud |
| Role | Admin do workspace — não-admins nunca veem a aba Forks |
| Self-hosted | Defina FORKING_ENABLED / NEXT_PUBLIC_FORKING_ENABLED (veja Setup self-hosted) |
No Zoen Cloud, sua organização também pode precisar ter o recurso ligado para a conta antes da aba aparecer.
Setup
1. Abra Forks
Vá em Settings → Enterprise → Workspace Forks no workspace a partir do qual quer fazer fork (ou gerenciar).
Você verá:
- Parent — se este workspace foi forked de outro
- Forks — filhos deste workspace
- See activity — histórico de forks, syncs e rollbacks
- Create fork — iniciar um novo filho
2. Crie um fork
Clique em Create fork. Nomeie o filho (padrão {workspace} (fork)) e revise Copy resources.
Tudo em Copy resources começa selecionado. Em geral é o que você quer: tabelas, bases de conhecimento, arquivos, custom tools, skills e servidores MCP de que o filho vai precisar.
Se você desmarcar um recurso, referências a ele nos workflows forked são limpas no filho. Você verá um aviso antes de confirmar.
Clique em Fork. O workspace filho é criado imediatamente. Workflows deployados aterrissam como drafts no filho. Conteúdo grande (linhas de tabela, arquivos de base de conhecimento, blobs de arquivo) pode terminar de copiar em background — acompanhe Activity no workspace fonte.
Só workflows deployados são forked. Drafts e trabalho não deployado ficam no pai. Se o pai não tiver nada deployado, o filho começa com um workflow starter em branco.
3. Abra a aresta do pai (a partir do filho)
Abra o workspace filho → Settings → Enterprise → Workspace Forks. Na linha Parent, abra o menu e escolha Edit mappings.
Linhas de filho (quando você está no pai) só oferecem Open workspace e Disconnect — mapping e sync são do filho configurando como se relaciona com o pai.
Open workspace fica desabilitado com um tooltip se você não tem acesso ao outro workspace. Disconnect continua disponível para você ainda poder cortar o link.
4. Entenda mappings
Um mapping significa: “este recurso na fonte é a mesma coisa lógica que aquele recurso no alvo.” Quando você sincroniza, campos de workflow que apontavam para o recurso fonte são reescritos para o recurso alvo para os blocos continuarem funcionando.
| Abordagem | Quando usar |
|---|---|
| Map | Ambos os lados já têm (ou devem manter) o próprio recurso — ex.: a credencial Slack, conta Gmail ou valor de secret de cada workspace |
| Copy | O alvo deve receber um novo clone do recurso fonte — uma nova tabela, base de conhecimento, arquivo ou config de servidor MCP |
Credentials e Secrets são só map. Nunca são copiados. Valores de secret nunca saem do workspace; só nomes como {{API_KEY}} aparecem no texto do workflow.
Mappings são salvos na relação de fork. Você pode clicar em Save sem sincronizar. Sync sempre usa os mappings salvos.
Depois de mapear ou copiar um recurso do pai (credential, knowledge base, table, …), campos dependentes — labels do Gmail, canais do Slack, documentos da base de conhecimento e similares — muitas vezes precisam de uma nova escolha no alvo. Dependentes obrigatórios bloqueiam Sync até serem preenchidos.
5. Mapeie, reconfigure e depois Sync
Na página de sync você verá direção (Push / Pull), mudanças de workflow deployadas, Mappings, Copy resources opcional e quaisquer itens Blocking sync.
- Push — sobrescreve o outro workspace com os workflows deployados deste workspace
- Pull — sobrescreve este workspace com os workflows deployados do outro
Ambos são operações force. Confirme com cuidado.
Recursos referenciados pelos workflows no sync vêm selecionados por padrão para copy. Os não usados ficam em Not used by any workflow (desligados por padrão). Se você map um recurso, ele sai da lista de copy — maps vencem.
Sync fica desabilitado até:
- Toda referência bloqueante estar mapeada, copiada ou corrigida na fonte
- Credentials e secrets obrigatórios estarem mapeados
- Campos dependentes obrigatórios estarem preenchidos
- Os detalhes do sync terem terminado de carregar
6. Confirme e rode
Clique em Sync. Você receberá uma confirmação de overwrite.
Em sucesso você verá um toast como Pushed to "…" ou Pulled from "…". Se alguns workflows falharem ao redeployar, você recebe um aviso para abri-los e redeployá-los manualmente.
Excluded workflows
A seção Excluded workflows na página Forks lista os workflows deployados deste workspace na estrutura de pastas da sidebar. Marque um workflow — ou uma pasta inteira de uma vez — para mantê-lo fora do forking por completo. Pense nisso como um .gitignore para syncs:
- Nunca enviado — pushes deste workspace não o carregam, o outro lado puxando deste workspace não o recebe, e criar um novo fork não o copia
- Nunca tocado — um sync para este workspace não o sobrescreve nem o arquiva, mesmo se a contraparte foi excluída no outro lado
A configuração pertence só à cópia deste workspace. Excluir um workflow aqui não exclui a contraparte no pai ou num fork — cada workspace gerencia a própria lista. Se o par já sincronizou antes, o link entre eles é mantido, então des-excluir depois retoma a atualização da mesma contraparte em vez de criar um duplicado.
Exemplo: um fork de staging exclui Scratch experiment para que nunca chegue à production, e production exclui Billing hotfix para que nenhum push de staging possa sobrescrevê-lo.
Activity
See activity (ou a visão Activity no header de Forks) lista forks, pushes, pulls e rollbacks que envolvem este workspace — incluindo eventos registrados no outro lado da aresta.
Expanda uma linha para nomes de workflows e recursos que foram criados, atualizados ou arquivados, e quaisquer avisos (por exemplo copies em background falhas ou falhas de deploy).
Rollback vs Disconnect
| Ação | O que faz | Tenha em mente |
|---|---|---|
| Rollback | Desfaz o último sync para este workspace — restaura cada workflow afetado à versão deployada anterior e remove workflows que o sync criou | Recursos copiados de syncs passados podem permanecer. Rollback não exclui tabelas, KBs ou arquivos que foram copiados. |
| Disconnect | Remove permanentemente a relação de fork | Ambos os workspaces ficam. Mappings salvos e histórico de sync do par são excluídos. Fazer fork de novo cria um novo filho, não um reconnect. |
Permissões
| Ação | Quem |
|---|---|
| Ver Forks / criar um fork | Admin neste workspace (+ recurso disponível) |
| Sync / editar mappings | Admin em ambos os lados da aresta |
| Rollback | Admin no workspace em que o sync aterrissou |
| Disconnect | Admin só neste lado (você pode disconnect mesmo sem acesso ao outro workspace) |
| Abrir o outro workspace | Você precisa ser membro daquele workspace |
Referência de recursos
Como cada recurso se comporta no fork vs no sync. Use isso ao decidir o que selecionar em Copy resources, ou por que Sync pede para mapear algo.
Visão geral
| Recurso | Fork | Sync |
|---|---|---|
| Workflows deployados | Copiados como drafts (a menos que excluídos) | Atualizados / criados / arquivados (force overwrite) |
| Workflows não deployados | Não copiados | Não sincronizados |
| Excluded workflows | Nunca | Nunca — não enviados, não sobrescritos, não arquivados |
| Files | Copy opcional (ligado por padrão) | Map ou copy |
| Tables | Copy opcional (ligado por padrão) | Map ou copy |
| Knowledge bases (+ documents) | Copy opcional; docs referenciados vêm com a KB | Map ou copy; documents seguem a KB |
| Custom tools | Copy opcional (ligado por padrão) | Map ou copy |
| Skills | Copy opcional (ligado por padrão) | Map ou copy |
| External MCP servers | Copy opcional (só config; sign-in limpo) | Map ou copy (só config; sign-in limpo) |
| Workflow MCP servers | Copy opcional (shells de server + attachments quando workflows copiam) | Mantidos em sync automaticamente com os workflows |
| Deployed chats | Levados com uma nova chat URL | Criados no alvo se ainda não tiver chat |
| Credentials | Nunca — campos limpos | Só map |
| Secrets | Valores nunca; nomes {{KEY}} mantidos | Só map de nomes de key |
| Public API | Filho começa private | Flag segue o workflow |
| Schedules / webhooks / triggers | Não ficam live até você deployar no filho | Seguem o que você deployar no alvo |
| History, API keys, memory, scheduled jobs | Nunca | Nunca |
Workflows
Só workflows deployados se movem. Deploy é o commit; sync é o force push/pull desses commits. Workflows marcados como excluded nunca se movem em nenhuma direção.
| Comportamento | |
|---|---|
| Fork | Cada workflow deployado vira um draft no filho. Histórico de execução não é copiado. Só pastas que contêm um workflow copiado são mantidas. |
| Sync | A lista de mudanças mostra o que será atualizado, criado ou arquivado. O alvo é sobrescrito para aqueles workflows. |
Exemplo: O pai tem Support triage deployado e WIP experiment como draft. O fork recebe só Support triage como draft. Um push posterior atualiza o filho a partir do deploy mais recente do pai de Support triage.
Files
| Comportamento | |
|---|---|
| Fork | Listados em Copy resources (ligado por padrão). Copies aterrissam na raiz de arquivos do filho (pastas originais de arquivo não são reconstruídas). Desmarcar → campos de arquivo nos workflows limpam. |
| Sync | Map para um arquivo que já existe no alvo, ou copy. Arquivos usados pelos workflows do sync vêm selecionados por padrão. |
Exemplo: Um workflow anexa brand-guide.pdf. Fork com Files selecionado → o filho tem a própria cópia e o bloco ainda aponta para ela.
Tables
| Comportamento | |
|---|---|
| Fork | Copy opcional (ligado por padrão). Linhas podem terminar de copiar em background depois que o fork é criado. Desmarcar → campos de tabela limpam. |
| Sync | Map se ambos os lados devem continuar apontando para “a mesma” tabela lógica pelo mapping, ou copy para um dataset independente no alvo. |
Exemplo: Um workflow de enrichment usa uma tabela “Leads”. Copy no fork para o filho experimentar sem tocar nos dados de production. No sync, map se você quer os dois lados alinhados a tabelas pareadas de propósito, ou copy uma nova tabela quando o alvo deve receber um clone fresco.
Knowledge bases e documents
| Comportamento | |
|---|---|
| Fork | Copy opcional (ligado por padrão). Definições de tag vêm com a base de conhecimento. Documents que os workflows forked de fato referenciam são incluídos. Desmarcar → campos de knowledge base / document limpam. |
| Sync | Map ou copy a knowledge base. Documents não são mapeados sozinhos — seguem a knowledge base (copiados com ela, ou reescolhidos quando você mapeia para uma existente). |
Exemplo: Um agente busca na knowledge base “Product docs.” Fork com aquela knowledge base selecionada → o filho recebe a base, tags e os documents que o agente usou. No sync, mapear para a “Product docs” existente do filho significa reescolher qual document a tool deve usar.
Custom tools
| Comportamento | |
|---|---|
| Fork | Copy opcional (ligado por padrão). A definição da tool vem junto para picks de agent / tool continuarem funcionando. |
| Sync | Map quando ambos os lados já mantêm a mesma tool; copy quando o alvo deve receber a definição da fonte como uma nova tool. |
Exemplo: Uma custom tool lookup_customer usada por um agente. Fork com Custom tools selecionado → o agente do filho ainda tem a tool. No push, uma tool nova no filho pode ser copiada para o pai se você a deixar selecionada em Copy resources.
Skills
| Comportamento | |
|---|---|
| Fork | Copy opcional (ligado por padrão). O conteúdo da skill vem junto. Links dentro da skill para arquivos ou outros recursos Zoen são atualizados quando aqueles recursos também foram copiados. Desmarcar → campos de skill em agentes limpam. |
| Sync | Map ou copy, a mesma ideia que custom tools. |
Exemplo: Uma skill “Support tone” num agente. Desmarcá-la no fork limpa a skill no agente do filho até você anexar uma de novo.
External MCP servers
Servidores que você conecta a um endpoint MCP externo (não “publicar este workflow como MCP”).
| Comportamento | |
|---|---|
| Fork | Copy opcional (ligado por padrão). Connection settings (URL, headers, transport) copiam. Sign-in / OAuth não é copiado — servidores OAuth aparecem desconectados até alguém entrar de novo no filho. Picks de tool em blocos MCP e agent seguem o novo server. |
| Sync | Map ou copy sob as mesmas regras. Mapping é típico quando cada workspace tem o próprio server apontando para o mesmo sistema upstream. |
Exemplo: Um servidor MCP para uma API interna. Depois do fork, abra as settings MCP no filho e complete OAuth (ou confirme headers de API) antes que aquelas tools rodem. No sync, mapeie servers filho ↔ pai para as seleções de tool sobreviverem a push e pull.
Workflow MCP servers
Servers que publicam workflows como tools MCP.
| Comportamento | |
|---|---|
| Fork | Opcional em Copy resources. Você recebe shells de server correspondentes no filho. Quando o workflow também foi forked, o attachment da tool naquele server é carregado. |
| Sync | Esses não aparecem na lista de mapping. Attachments ficam alinhados conforme você sincroniza — tools são adicionadas, atualizadas ou removidas para bater com a fonte. |
Exemplo: O pai expõe Support triage num workflow MCP server. Fork com Workflow MCP servers selecionado → o filho recebe um server correspondente e o attachment para a cópia do workflow no filho.
Deployed chats
| Comportamento | |
|---|---|
| Fork | Deployments de chat live em workflows copiados vêm junto com uma nova chat URL. Histórico de conversa não é copiado — só o setup do chat (incluindo quais blocos alimentam o chat). |
| Sync | Se o workflow alvo ainda não tem chat, o chat live da fonte é criado lá (de novo com uma nova URL). Chats existentes no alvo são deixados em paz. Workflows que não estão prontos para deploy não recebem chat. |
Exemplo: O pai tem um chat público em Support triage. O fork recebe a própria chat URL na hora. Um push posterior para um workflow do pai que nunca teve chat pode criar um lá.
Credentials
| Comportamento | |
|---|---|
| Fork | Nunca copiadas. Campos de credential nos workflows são limpos. Conecte ou escolha credentials no filho. |
| Sync | Só map. Toda credential usada pelos workflows sincronizados precisa ser mapeada para uma credential no alvo (mesmo tipo de integração). Sync fica bloqueado até isso ser feito. Depois reescolha dependentes (labels, calendars, channels, …). |
Exemplo: Um bloco Gmail usando “Support inbox.” Fork limpa. Antes do primeiro sync, mapeie para a credential “Support inbox” do filho e reescolha o label.
Secrets (variáveis de ambiente)
| Comportamento | |
|---|---|
| Fork | Valores nunca saem da fonte. O texto do workflow ainda contém nomes {{KEY}}. Crie secrets correspondentes (ou os nomes para os quais vai mapear) em Secrets do filho. |
| Sync | Mapeie nomes de key da fonte para nomes de key do alvo. Valores ficam em cada workspace. Secrets obrigatórios não mapeados bloqueiam Sync. |
Exemplo: Workflows usam {{OPENAI_API_KEY}}. Depois do fork, adicione aquele secret no filho (ou mapeie OPENAI_API_KEY para o nome que o filho usa) antes que runs e syncs tenham sucesso.
Public API
| Comportamento | |
|---|---|
| Fork | Workflows filhos começam private — não expostos como endpoints de public API, mesmo se o pai estava. |
| Sync | A configuração de public API do workflow fonte é carregada. Faça push de um endpoint público e o alvo também fica público. |
Não carregados
Estes não se movem no fork nem no sync:
- Workflows não deployados e drafts locais
- Histórico de execução / runs
- API keys do Zoen
- Memory stores e scheduled jobs
- Keys de provedor BYOK
- Grupos de permissão (o filho herda a organização, mas grupos não são aplicados especialmente pelo forking)
Schedules, webhooks e triggers não ficam live no filho até você deployar lá — a mesma regra “deploy = commit”.
Edge cases a ter em mente
- Force overwrite — Sync não faz merge de mudanças do canvas. Qualquer coisa só no alvo que conflita com os workflows deployados da fonte pode ser perdida. Use a lista de archive do diálogo de confirmação com cuidado.
- Desmarcar no fork — Referências limpas são intencionais. Prefira copiar o recurso, ou planeje reconectá-lo no filho.
- Copy em background — Logo depois do fork, tabelas / knowledge bases / arquivos grandes ainda podem estar copiando. Cheque Activity se algo parecer vazio.
- OAuth MCP — Espere um reconnect no filho (e depois de um server copiado no sync).
- Rollback ≠ desfazer copies — Versões de workflow fazem rollback; recursos copiados podem permanecer como órfãos.
- Disconnect é permanente — Você não pode “reconectar” a mesma aresta; faria fork de novo num novo workspace.
- Sem sync com avô — Só o par direto pai↔filho.
Common Questions
Setup self-hosted
Deployments self-hosted ligam Forks com uma variável de ambiente em vez do plano Enterprise.
| Variável | Descrição |
|---|---|
FORKING_ENABLED, NEXT_PUBLIC_FORKING_ENABLED | Habilita forking de workspace quando billing não é usado como gate de entitlement |
Uma vez habilitado, use a mesma UI Settings → Enterprise → Workspace Forks do Zoen Cloud. Só admins de workspace podem gerenciar forks.