Criar um modelo de pipeline

Os modelos de pipeline são criados nas configurações do espaço de trabalho. A entrada Pipelines na barra lateral do espaço de trabalho é a fila de execuções, não a lista de modelos — ela não tem nenhuma ação de “criar modelo”.

Para saber o que cada tipo de etapa, chave de corpo e campo de configuração significa, consulte a referência de etapas de pipeline.

Criar um modelo

1. Acesse Configurações → Espaço de trabalho → Modelos de pipeline (/workspaces/<workspace-id>/settings/pipelines).
2. Pressione Novo modelo.

Não há diálogo de id. O editor abre imediatamente em um esqueleto semeado chamado Novo pipeline, com um id alocado automaticamente (pipeline_1, depois pipeline_2, …). Clique no título no cabeçalho para renomeá-lo.

O canvas não vem em branco: um nó de entrada Trigger, um nó de agente de prompt rotulado Step e uma sentinela terminal que encerra a execução. A sentinela não é desenhada. O editor reconecta esse terminal oculto a cada sumidouro alcançável, de modo que o trabalho que você anexar depois do Step ainda é executado.

Adicionar nós

A barra lateral Biblioteca de nós fica permanentemente à esquerda do editor. Filtre-a com a caixa Pesquisar nós e arraste uma entrada até o canvas — o nó cai onde você o solta, sem nenhuma conexão de entrada.

Nó da paleta	Tipo de etapa	O que faz
Bash script	listen	Executa um script de shell com substituição de {{state}}; nenhum agente é despachado
Open conversation	listen	Abre o único espaço visível da execução e o checkout dele; os nós de agente entram nessa sala
Clone PR branch	listen	Descobre o branch de head da PR via gh pr view e o clona no diretório da execução
Post PR comment	listen	Publica os achados consolidados na PR como um comentário de revisão do GitHub
Reviewer (prompt)	listen	Despacha um agente revisor especialista; suspende até que o agente envie o resultado dele
Consolidate (join)	join	Aguarda vários ramos a montante e então pede a um agente que consolide as saídas deles
Custom prompt	listen	Nó genérico guiado por prompt, roteado pelo corpo promptAgent
Post to space	listen	Envia uma mensagem para um espaço de mensagens
Condition / switch (router)	router	Ramifica o fluxo com base em um valor do estado
If file exists (router)	router	Roteia "true" quando um caminho existe sob o clone, senão "false"
Any file exists (OR router)	router	Roteia "true" quando qualquer caminho listado existe
All conditions (AND router)	router	Roteia "true" somente quando todos os caminhos listados existem
Team dispatch	listen	Despacha uma equipe inteira e suspende até que ela termine
Approval gate	listen	Pausa para uma decisão de aprovação
For each (map)	forEach	Renderiza um prompt por item e então despacha o agente uma vez com esses prompts reunidos
Call sub-pipeline	listen	Executa outro modelo como uma etapa aninhada
Clean up worktrees	listen	Remove worktrees isoladas obsoletas; determinístico, nenhum agente é despachado

A biblioteca agrupa tudo isso em Fluxo e lógica, Revisão de PR, Agentes, Mensagens e Código. Não há grupo Demo.

Conectar nós entre si

Cada nó de trabalho tem uma porta de saída circular na borda direita. Arraste dessa porta até outro nó para conectá-los. Os gatilhos de início funcionam do mesmo jeito: cada um tem a própria porta, então uma conexão que sai de Programação não sai também de Execução manual. Pressione Adicionar passo (+) logo depois de um nó para inserir um tipo após ele. Passe o mouse sobre o ponto médio de uma aresta existente e pressione × para desconectar.

As conexões também são editadas a partir do nó que as recebe:

1. Selecione o nó a jusante. O painel de configuração dele abre à direita.
2. Role até Triggers from e toque no chip de cada nó a montante que este deve escutar. Tocar em um chip selecionado remove a conexão.
3. Se um nó a montante for um roteador, um bloco Chaves de rota aparece sob os chips, com um campo Chave de rota de <node> por aresta de roteador. Informe a chave com que essa aresta dispara — true ou false para os roteadores de existência de arquivos, ou o nome do caso para um comutador.

Cada nó de gatilho é um ponto de entrada. Um nó pode escutar vários nós a montante (fan-in) e alimentar vários a jusante (fan-out), e o grafo deve permanecer acíclico — nada no editor impede você de criar um ciclo, então confira seu trabalho.

A sentinela terminal é filtrada do canvas, então não pode ser selecionada. O editor a reconecta a cada sumidouro alcançável sempre que o grafo muda, de modo que o trabalho que você anexar depois do Step semeado ainda é executado. Um grafo vazio (gatilho sem sucessores de trabalho) lista o próprio gatilho para que uma execução seja concluída imediatamente.

Configurar um nó

Selecione um nó para abrir o painel de configuração dele. Quais campos aparecem depende do corpo do nó.

Todo nó tem Rótulo, Chaves de entrada (chaves de estado separadas por vírgula, lidas no momento da execução) e, em Avançado, Redutor, Tempo limite (ms), Tentativas de repetição, Continuar se esta etapa falhar e Esquema de saída (JSON). Nós de escuta e de junção também podem alternar o Tipo deles entre os dois.

Open conversation

Adiciona um seletor de escopo de repos (quais repos do espaço de trabalho fazer checkout; vazio significa nenhum), um Nome do espaço e uma caixa de seleção Criar conversa. Quando essa caixa está marcada, um campo Título da conversa nomeia o fluxo com que a sala abre. Os nós de agente entram nessa sala — eles não abrem uma própria.

Prompt agent

Adiciona Agente (qual agente despachar), Prompt (use {{key}} para referenciar entradas ou saídas a montante) e Chave de saída.

Tempo limite (ms) está em milissegundos, não segundos — 900000 são 15 minutos. Informar 900 dá à etapa 0,9 segundo.

O modo de conversa sob o qual um nó de agente de prompt é executado não tem campo no editor do nó de agente. Ele vem de extras['mode'] (chat, plan ou review) no nó Open conversation que criou a sala (padrão review). Defini-lo em uma etapa de agente é ignorado. A chave é correspondida exatamente: qualquer outra grafia é ignorada em silêncio.

Bash script

Adiciona Script. Não há campos de diretório de trabalho nem de ambiente, porque nenhum dos dois é configurável:

• Toda etapa bash de uma execução compartilha o cwd <cc_root>/pipelines/<runId>/.
• GITHUB_TOKEN é injetado a partir do armazenamento de credenciais, então gh e git clone https://x-access-token:$GITHUB_TOKEN@… funcionam sem configuração.
• O script é iniciado como o executável literal bash, então bash deve estar no PATH do host do servidor. Isso é uma consideração do Windows.

Router

Um roteador avalia uma condição e retorna uma chave de rota; o motor dispara apenas a aresta a jusante cuja chave de rota corresponde e marca os outros ramos como ignorados.

Selecionar um roteador substitui o campo Chave de saída pelo editor de condições. Escolha um dos quatro modos dele:

• Arquivo(s) existe(m) — algum — roteia "true" quando qualquer caminho listado existe.
• Arquivos existem — todos — roteia "true" somente quando todos os caminhos listados existem.
• Comparação — compara um valor de estado com um literal.
• Comutador — roteia com base no valor de uma chave de estado, com um caso padrão.

Depois, defina as chaves de rota correspondentes nas arestas de saída (consulte Conectar nós entre si).

Grupos booleanos and / or / not são aceitos pelo corpo, mas não podem ser criados por este formulário — eles exigem uma árvore de predicados escrita à mão em extras.predicate. O vocabulário completo de predicados e operadores está na referência de etapas de pipeline.

Join

Não tem configuração própria: espera por todas as etapas a montante dele.

Approval gate

O portão despacha o agente aprovador para uma conversa oculta com o prompt do portão e suspende. O aprovador busca a sua decisão na conversa e a envia com submit_output como { "decision": "approved" | "rejected", "reason": "..." }. A decisão cai sob a chave de saída (padrão approval_decision), então um roteador de comutador a jusante pode ramificar com base nela.

Defina Agente como o aprovador e Prompt como a pergunta do portão. O portão é resolvido por meio de submit_output como { "decision": "approved" | "rejected", "reason": "..." }. Nós Reviewer (prompt) enviam da mesma forma.

Team dispatch

Adiciona ID da equipe e Modo de despacho. O seletor oferece exatamente dois modos:

• allParallel — uma tarefa por membro, suspende até que todas terminem.
• manager — despacha o líder, que delega.

Qualquer outro valor armazenado se comporta como allParallel. Defina Redutor como append para recolher o resultado de cada membro em uma lista sob a chave de saída.

For each e Call sub-pipeline

For each mapeia sobre a chave de estado items por padrão (extras.iterableKey / extras.itemKey no nó). Ele renderiza o prompt uma vez por item ({{item}} por padrão) e despacha o agente uma vez com esses prompts concatenados. Uma coleção vazia é concluída imediatamente com uma lista vazia. Não é um despacho paralelo por item.

Call sub-pipeline suspende até que a execução filha alcance um estado terminal e então mescla o estado final da filha sob a chave de saída (padrão subflow_result). Aponte-o para uma filha com extras.templateId. Um modelo não pode chamar a si mesmo; uma filha com falha ou cancelada faz a etapa pai falhar, e isso então alimenta a política de nova tentativa e continue-on-fail dessa etapa.

Declarar entradas e permitir execuções manuais

Os dois ficam atrás de Execução manual no cabeçalho do editor.

1. Pressione Execução manual.
2. Ative Permitir execução manual. Esse interruptor persiste imediatamente — ele cria (ou exclui) a linha de gatilho manual que faz o modelo aparecer no seletor de execuções.
3. Defina Execuções paralelas máx. se quiser um limite (deixe vazio para ilimitado). Inícios extras esperam em um estado queued até que uma vaga seja liberada.
4. Pressione Adicionar entrada para cada campo de formulário que uma execução manual deve coletar:

Campo	Descrição
Chave	Chave de estado sob a qual o valor é armazenado; referencie-a como {{key}}
Rótulo	Rótulo de exibição (o padrão é a chave)
Tipo	Texto, Texto de várias linhas, Número, Alternância, Seleção, Repositório
Opções	Escolhas separadas por vírgula, apenas para Seleção
Valor predefinido	Valor preenchido previamente
Marcador de posição	Texto de dica dentro do campo vazio
Texto de ajuda	Texto auxiliar sob o campo
Obrigatório	Se o formulário de execução fica bloqueado com um valor vazio

Uma entrada Repositório renderiza um seletor com os repos do espaço de trabalho e preenche repo_id, repo_local_path, repo_full_name e — quando o repo tem um remoto do GitHub — repo_owner e repo_name no payload da execução.

5. Pressione Salvar na caixa de diálogo. As edições nas entradas são incorporadas ao rascunho; elas persistem quando você salva o modelo.

Salvar e ativar

1. Pressione Salvar no cabeçalho do editor. O cabeçalho mostra “Alterações não salvas” até que você faça isso.
2. Volte para Configurações → Espaço de trabalho → Modelos de pipeline e verifique se o interruptor da linha do modelo está ativado. O motor se recusa a iniciar um modelo desativado, e um modelo desativado nunca aparece no seletor de execuções.
3. Para iniciá-lo automaticamente, arraste um gatilho da biblioteca de nós até o canvas — consulte Configurar gatilhos de pipeline.

Guias relacionados

• Executar um pipeline manualmente
• Configurar gatilhos de pipeline
• Monitorar execuções de pipeline
• Referência de etapas de pipeline

Conceitos relacionados

• Pipelines