Os Workspace Forks permitem clonar um workspace em um filho, manter os dois vinculados e mover mudanças de workflows com deploy entre eles depois. Pense em Deploy como um commit do git: só o que você deu deploy é o que os Forks conseguem copiar ou sincronizar. O Sync é sempre um force push ou um force pull — o lado de destino é sobrescrito para os workflows incluídos na sincronização. Não existe interface 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 — nunca com um avô ou um irmão.
Quem pode usar os Forks
| Requisito | Detalhe |
|---|---|
| Plano | Enterprise no Studio Cloud |
| Papel | Admin do workspace — quem não é admin nunca vê a aba Forks |
| Auto-hospedagem | Defina FORKING_ENABLED / NEXT_PUBLIC_FORKING_ENABLED (veja Configuração em auto-hospedagem) |
No Studio Cloud, sua organização também pode precisar ter o recurso ativado para sua conta antes de a aba aparecer.
Configuração
1. Abra os Forks
Vá para Settings → Enterprise → Workspace Forks no workspace do qual você quer criar o fork (ou que você quer gerenciar).
Você verá:
- Parent — se este workspace foi criado como fork de outro
- Forks — os filhos deste workspace
- See activity — histórico de forks, sincronizações e rollbacks
- Create fork — criar um novo filho
2. Crie um fork
Clique em Create fork. Dê um nome ao filho (o padrão é {workspace} (fork)) e revise Copy resources.
Tudo em Copy resources começa selecionado. Normalmente é isso que você quer: tabelas, bases de conhecimento, arquivos, ferramentas personalizadas, skills e servidores MCP de que o filho vai precisar.
Se você desmarcar um recurso, as referências a ele nos workflows do fork são limpas no filho. Você verá um aviso antes de confirmar.
Clique em Fork. O workspace filho é criado na hora. Os workflows com deploy chegam como drafts no filho. Conteúdo grande (linhas de tabela, arquivos de base de conhecimento, blobs de arquivo) pode terminar de ser copiado em segundo plano — acompanhe Activity no workspace de origem.
Somente workflows com deploy entram no fork. Drafts e trabalho sem deploy ficam no pai. Se o pai não tiver nada com deploy, o filho começa com um workflow inicial 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.
As linhas de filhos (quando você está no pai) oferecem apenas Open workspace e Disconnect — o mapeamento e a sincronização pertencem ao filho, que configura como se relaciona com o pai.
Open workspace fica desabilitado com um tooltip se você não tiver acesso ao outro workspace. Disconnect continua disponível, para que você ainda possa cortar o vínculo.
4. Entenda os mappings
Um mapping significa: “este recurso na origem é a mesma coisa, logicamente, que aquele recurso no destino”. Quando você sincroniza, os campos de workflow que apontavam para o recurso de origem são reescritos para o recurso de destino, de forma que os blocks continuem funcionando.
| Abordagem | Quando usar |
|---|---|
| Map | Os dois lados já têm (ou devem manter) o próprio recurso — por exemplo, a credencial do Slack, a conta do Gmail ou o valor de secret de cada workspace |
| Copy | O destino deve receber um clone novo do recurso de origem — uma nova tabela, base de conhecimento, arquivo ou configuração de servidor MCP |
Credentials e Secrets são map-only. Eles nunca são copiados. Valores de secret nunca saem do seu workspace; só nomes como {{API_KEY}} aparecem no texto do workflow.
Os mappings são salvos na relação de fork. Você pode clicar em Save sem sincronizar. O Sync sempre usa os mappings salvos.
Depois de mapear ou copiar um recurso do pai (credencial, base de conhecimento, tabela, …), os campos dependentes — labels do Gmail, canais do Slack, documentos de base de conhecimento e afins — muitas vezes precisam de uma nova escolha no destino. Dependentes obrigatórios bloqueiam o Sync até serem preenchidos.
5. Mapeie, reconfigure e sincronize
Na página de sincronização você verá a direção (Push / Pull), as mudanças de workflows com deploy, os Mappings, o Copy resources opcional e qualquer item em Blocking sync.
- Push — sobrescreve o outro workspace com os workflows com deploy deste workspace
- Pull — sobrescreve este workspace com os workflows com deploy do outro
As duas são operações de força. Confirme com atenção.
Recursos referenciados pelos workflows da sincronização vêm selecionados para cópia por padrão. Os não utilizados ficam em Not used by any workflow (desmarcados por padrão). Se você mapear um recurso, ele sai da lista de cópia — o mapeamento vence.
O Sync fica desabilitado até que:
- Toda referência bloqueante esteja mapeada, copiada ou corrigida na origem
- As credenciais e secrets obrigatórios estejam mapeados
- Os campos dependentes obrigatórios estejam preenchidos
- Os detalhes da sincronização terminem de carregar
6. Confirme e execute
Clique em Sync. Você receberá uma confirmação de sobrescrita.
Em caso de sucesso, você verá um toast como Pushed to "…" ou Pulled from "…". Se algum workflow falhar no redeploy, você recebe um aviso para abri-lo e refazer o deploy manualmente.
Excluded workflows
A seção Excluded workflows na página de Forks lista os workflows com deploy deste workspace na estrutura de pastas da sidebar. Marque um workflow — ou uma pasta inteira de uma vez — para mantê-lo totalmente fora do forking. Pense nisso como um .gitignore para as sincronizações:
- Nunca enviado — pushes deste workspace não o levam, o outro lado que faz pull deste workspace não o recebe e criar um novo fork não o copia
- Nunca tocado — uma sincronização para dentro deste workspace não o sobrescreve nem o arquiva, mesmo que sua contraparte tenha sido excluída do outro lado
A configuração pertence apenas à cópia deste workspace. Excluir um workflow aqui não exclui sua contraparte no pai nem em um fork — cada workspace gerencia sua própria lista. Se o par já sincronizou antes, o vínculo entre eles é mantido, então remover a exclusão depois volta a atualizar a mesma contraparte em vez de criar uma duplicata.
Exemplo: um fork de staging exclui Scratch experiment para que ele nunca chegue à produção, e a produção exclui Billing hotfix para que nenhum push do staging possa sobrescrevê-lo.
Activity
See activity (ou a visão Activity no cabeçalho de Forks) lista forks, pushes, pulls e rollbacks que envolvem este workspace — incluindo eventos registrados do outro lado da aresta.
Expanda uma linha para ver os nomes dos workflows e recursos que foram criados, atualizados ou arquivados, além de qualquer aviso (por exemplo, cópias em segundo plano que falharam ou falhas de deploy).
Rollback vs. Disconnect
| Ação | O que faz | Pontos de atenção |
|---|---|---|
| Rollback | Desfaz a última sincronização recebida por este workspace — restaura cada workflow afetado para a versão anterior com deploy e remove os workflows que a sincronização criou | Recursos copiados em sincronizações anteriores podem permanecer. O Rollback não exclui tabelas, bases de conhecimento ou arquivos que foram copiados. |
| Disconnect | Remove a relação de fork permanentemente | Os dois workspaces continuam existindo. Os mappings salvos e o histórico de sincronização do par são excluídos. Criar um fork novamente gera um novo filho, não uma reconexão. |
Permissões
| Ação | Quem |
|---|---|
| Ver os Forks / criar um fork | Admin deste workspace (+ recurso disponível) |
| Sincronizar / editar mappings | Admin dos dois lados da aresta |
| Rollback | Admin do workspace que recebeu a sincronização |
| Disconnect | Admin apenas deste lado (você pode desconectar 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 momento do fork e no momento do sync. Use esta seção para decidir o que selecionar em Copy resources ou para entender por que o Sync está pedindo que você mapeie algo.
Visão geral
| Recurso | Fork | Sync |
|---|---|---|
| Workflows com deploy | Copiados como drafts (a menos que excluídos) | Atualizados / criados / arquivados (sobrescrita forçada) |
| Workflows sem deploy | Não copiados | Não sincronizados |
| Excluded workflows | Nunca | Nunca — não são enviados, sobrescritos nem arquivados |
| Arquivos | Cópia opcional (ligada por padrão) | Map ou copy |
| Tabelas | Cópia opcional (ligada por padrão) | Map ou copy |
| Bases de conhecimento (+ documentos) | Cópia opcional; os documentos referenciados vêm com a base | Map ou copy; os documentos seguem a base |
| Ferramentas personalizadas | Cópia opcional (ligada por padrão) | Map ou copy |
| Skills | Cópia opcional (ligada por padrão) | Map ou copy |
| Servidores MCP externos | Cópia opcional (somente configuração; login limpo) | Map ou copy (somente configuração; login limpo) |
| Servidores MCP de workflow | Cópia opcional (estruturas de servidor + anexos quando os workflows são copiados) | Mantidos em sincronia automaticamente com os workflows |
| Chats com deploy | Levados com uma nova URL de chat | Criados no destino, se ele ainda não tiver chat |
| Credenciais | Nunca — os campos são limpos | Somente map |
| Secrets | Valores nunca; nomes {{KEY}} mantidos | Somente mapeamento dos nomes das chaves |
| API pública | O filho começa privado | A flag acompanha o workflow |
| Agendamentos / webhooks / triggers | Não ficam ativos até você dar deploy no filho | Seguem o que você der deploy no destino |
| Histórico, API keys, memória, jobs agendados | Nunca | Nunca |
Workflows
Só workflows com deploy se movem. O deploy é o commit; o sync é o force push/pull desses commits. Workflows marcados como excluídos nunca se movem em nenhuma direção.
| Comportamento | |
|---|---|
| Fork | Cada workflow com deploy se torna um draft no filho. O histórico de execuções não é copiado. Só as 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 destino é sobrescrito para esses workflows. |
Exemplo: o pai tem Support triage com deploy e WIP experiment como draft. O fork recebe apenas Support triage, como draft. Um push posterior atualiza o filho com o último deploy de Support triage feito no pai.
Arquivos
| Comportamento | |
|---|---|
| Fork | Listado em Copy resources (ligado por padrão). As cópias chegam na raiz de arquivos do filho (as pastas originais não são recriadas). Desmarcar → os campos de arquivo nos workflows são limpos. |
| Sync | Mapeie para um arquivo que já existe no destino ou copie. Arquivos usados pelos workflows da sincronização vêm selecionados por padrão. |
Exemplo: um workflow anexa brand-guide.pdf. Faça o fork com Files selecionado → o filho tem a própria cópia e o block continua apontando para ela.
Tabelas
| Comportamento | |
|---|---|
| Fork | Cópia opcional (ligada por padrão). As linhas podem terminar de ser copiadas em segundo plano depois que o fork é criado. Desmarcar → os campos de tabela são limpos. |
| Sync | Mapeie se os dois lados devem continuar apontando para “a mesma” tabela lógica por meio do mapeamento, ou copie para ter um conjunto de dados independente no destino. |
Exemplo: um workflow de enriquecimento usa uma tabela “Leads”. Copie no fork para que o filho possa experimentar sem tocar nos dados de produção. No sync, mapeie se você quiser intencionalmente alinhar os dois lados a tabelas pareadas, ou copie uma nova tabela quando o destino precisar de um clone novo.
Bases de conhecimento e documentos
| Comportamento | |
|---|---|
| Fork | Cópia opcional (ligada por padrão). As definições de tag vêm com a base de conhecimento. Os documentos que os workflows do fork realmente referenciam são incluídos. Desmarcar → os campos de base de conhecimento / documento são limpos. |
| Sync | Mapeie ou copie a base de conhecimento. Os documentos não são mapeados por si — eles seguem a base de conhecimento (copiados com ela ou escolhidos novamente quando você mapeia para uma base existente). |
Exemplo: um agente busca na base de conhecimento “Product docs”. Faça o fork com essa base selecionada → o filho recebe a base, as tags e os documentos que o agente usou. No sync, mapear para a base “Product docs” existente no filho significa escolher novamente qual documento a ferramenta deve usar.
Ferramentas personalizadas
| Comportamento | |
|---|---|
| Fork | Cópia opcional (ligada por padrão). A definição da ferramenta vai junto, para que as escolhas de agente / ferramenta continuem funcionando. |
| Sync | Mapeie quando os dois lados já mantêm a mesma ferramenta; copie quando o destino precisar receber a definição da origem como uma nova ferramenta. |
Exemplo: uma ferramenta personalizada lookup_customer usada por um agente. Faça o fork com Custom tools selecionado → o agente do filho continua com a ferramenta. Em um push, uma ferramenta totalmente nova no filho pode ser copiada para o pai se você deixá-la selecionada em Copy resources.
Skills
| Comportamento | |
|---|---|
| Fork | Cópia opcional (ligada por padrão). O conteúdo da skill vai junto. Links dentro da skill para arquivos ou outros recursos do Studio são atualizados quando esses recursos também foram copiados. Desmarcar → os campos de skill nos agentes são limpos. |
| Sync | Mapeie ou copie, com a mesma ideia das ferramentas personalizadas. |
Exemplo: uma skill “Support tone” em um agente. Desmarcá-la no fork limpa a skill no agente do filho até você anexar outra.
Servidores MCP externos
Servidores que você conecta a um endpoint MCP externo (não o “publicar este workflow como MCP”).
| Comportamento | |
|---|---|
| Fork | Cópia opcional (ligada por padrão). As configurações de conexão (URL, headers, transporte) são copiadas. O login / OAuth não é copiado — servidores com OAuth aparecem desconectados até que alguém faça login novamente no filho. As escolhas de ferramenta nos blocks MCP e Agent seguem o novo servidor. |
| Sync | Mapeie ou copie sob as mesmas regras. O mapeamento é o caminho típico quando cada workspace tem o próprio servidor apontando para o mesmo sistema upstream. |
Exemplo: um servidor MCP para uma API interna. Depois do fork, abra as configurações de MCP no filho e conclua o OAuth (ou confirme os headers da API) antes que essas ferramentas funcionem. No sync, mapeie os servidores do filho ↔ do pai para que as seleções de ferramenta sobrevivam a pushes e pulls.
Servidores MCP de workflow
Servidores que expõem workflows como ferramentas MCP.
| Comportamento | |
|---|---|
| Fork | Opcional em Copy resources. Você recebe estruturas de servidor equivalentes no filho. Quando o workflow também entrou no fork, seu anexo de ferramenta nesse servidor é levado junto. |
| Sync | Eles não aparecem na lista de mapeamento. Os anexos permanecem alinhados conforme você sincroniza — ferramentas são adicionadas, atualizadas ou removidas para corresponder à origem. |
Exemplo: o pai expõe Support triage em um servidor MCP de workflow. Faça o fork com Workflow MCP servers selecionado → o filho recebe um servidor equivalente e o anexo à cópia do workflow no filho.
Chats com deploy
| Comportamento | |
|---|---|
| Fork | Deploys de chat ativos em workflows copiados vão junto, com uma nova URL de chat. O histórico de conversas não é copiado — apenas a configuração do chat (incluindo quais blocks alimentam o chat). |
| Sync | Se o workflow de destino ainda não tiver chat, o chat ativo da origem é criado lá (também com uma nova URL). Chats existentes no destino não são alterados. 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 ganha a própria URL de chat imediatamente. Um push posterior para um workflow do pai que nunca teve chat pode criar um lá.
Credenciais
| Comportamento | |
|---|---|
| Fork | Nunca copiadas. Os campos de credencial nos workflows são limpos. Conecte ou escolha as credenciais no filho. |
| Sync | Somente map. Toda credencial usada pelos workflows sincronizados precisa ser mapeada para uma credencial no destino (do mesmo tipo de integração). O Sync fica bloqueado até isso ser feito. Depois, escolha novamente os dependentes (labels, calendários, canais, …). |
Exemplo: um block do Gmail usando “Support inbox”. O fork limpa esse campo. Antes da primeira sincronização, mapeie-o para a credencial “Support inbox” do filho e escolha a label de novo.
Secrets (variáveis de ambiente)
| Comportamento | |
|---|---|
| Fork | Os valores nunca saem da origem. O texto do workflow continua com os nomes {{KEY}}. Crie os secrets correspondentes (ou os nomes para os quais você vai mapear) em Secrets no filho. |
| Sync | Mapeie os nomes das chaves de origem para os nomes das chaves de destino. Os valores permanecem em cada workspace. Secrets obrigatórios não mapeados bloqueiam o Sync. |
Exemplo: os workflows usam {{OPENAI_API_KEY}}. Depois do fork, adicione esse secret no filho (ou mapeie OPENAI_API_KEY para o nome que o filho usa) antes que execuções e sincronizações funcionem.
API pública
| Comportamento | |
|---|---|
| Fork | Os workflows do filho começam privados — não expostos como endpoints de API pública, mesmo que o pai estivesse. |
| Sync | A configuração de API pública do workflow de origem é levada. Faça push de um endpoint público e o destino também fica público. |
Não levados
Estes não se movem nem no fork nem no sync:
- Workflows sem deploy e drafts locais
- Histórico de execuções
- API keys do Studio
- Stores de memória e jobs agendados
- Chaves de provider BYOK
- Grupos de permissões (o filho herda a organização, mas os grupos não são aplicados de forma especial pelo forking)
Agendamentos, webhooks e triggers não ficam ativos no filho até você dar deploy lá — a mesma regra de “deploy = commit”.
Casos de borda para ter em mente
- Sobrescrita forçada — o Sync não mescla mudanças feitas no workflow builder. Qualquer coisa que exista apenas no destino e conflite com os workflows com deploy da origem pode ser perdida. Leia com atenção a lista de arquivamento no diálogo de confirmação.
- Desmarcar no fork — as referências limpas são intencionais. Prefira copiar o recurso ou planeje reconectá-lo no filho.
- Cópia em segundo plano — logo depois do fork, tabelas / bases de conhecimento / arquivos grandes podem ainda estar sendo copiados. Confira Activity se algo parecer vazio.
- MCP com OAuth — espere uma reconexão no filho (e também depois de um servidor copiado em uma sincronização).
- Rollback ≠ desfazer cópias — as versões de workflow voltam atrás; os recursos copiados podem permanecer como órfãos.
- Disconnect é permanente — você não pode “reconectar” a mesma aresta; seria preciso fazer um novo fork para um novo workspace.
- Sem sincronização com o avô — apenas o par direto pai↔filho.
Common Questions
Configuração em auto-hospedagem
Instalações auto-hospedadas ativam os Forks com uma variável de ambiente, em vez do plano Enterprise.
| Variável | Descrição |
|---|---|
FORKING_ENABLED, NEXT_PUBLIC_FORKING_ENABLED | Habilita o forking de workspaces quando o billing não é usado como controle de acesso ao recurso |
Uma vez habilitado, use a mesma interface de Settings → Enterprise → Workspace Forks do Studio Cloud. Somente admins de workspace podem gerenciar forks.