Criar um modelo de pipeline

Os modelos de pipeline criam-se nas definições do espaço de trabalho. A entrada Pipelines na barra lateral do espaço de trabalho é a fila de execuções, e não a lista de modelos — não tem nenhuma ação «criar modelo».

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

Criar um modelo

1. Aceda a Definições → Espaço de trabalho → Modelos de pipeline (/workspaces/<workspace-id>/settings/pipelines).
2. Prima Novo modelo.

Não há nenhuma caixa de diálogo de id. O editor abre imediatamente num esqueleto pré-preenchido chamado Novo pipeline, com um id atribuído automaticamente (pipeline_1, depois pipeline_2, …). Clique no título no cabeçalho para o renomear.

O canvas não está vazio: um nó de entrada Trigger, um nó de agente de prompt com o rótulo Step e um sentinela terminal que termina a execução. O sentinela não é desenhado. O editor volta a ligar esse terminal oculto a todos os sumidouros alcançáveis, para que o trabalho que ligar depois de Step continue a ser executado.

Adicionar nós

A barra lateral Biblioteca de nós está permanentemente à esquerda do editor. Filtre-a com a caixa Pesquisar nós e arraste uma entrada para o canvas — o nó fica onde o largar, sem nenhuma conexão de entrada.

Nó da paleta	Tipo de passo	O que faz
Bash script	listen	Executa um script de shell com substituição de {{state}}; não é despachado nenhum agente
Open conversation	listen	Abre o único espaço visível da execução e o respetivo checkout; os nós de agente juntam-se a esta sala
Clone PR branch	listen	Descobre o branch de cabeça da PR através de gh pr view e clona-o para o diretório da execução
Post PR comment	listen	Publica as constatações consolidadas na PR como comentário de revisão do GitHub
Reviewer (prompt)	listen	Despacha um agente revisor especializado; suspende-se até que o agente submeta o seu resultado
Consolidate (join)	join	Espera por vários ramos a montante e depois pede a um agente que consolide as respetivas saídas
Custom prompt	listen	Nó genérico orientado por prompt, encaminhado 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 num valor de estado
If file exists (router)	router	Encaminha "true" quando existe um caminho sob o clone, senão "false"
Any file exists (OR router)	router	Encaminha "true" quando existe qualquer um dos caminhos indicados
All conditions (AND router)	router	Encaminha "true" apenas quando existem todos os caminhos indicados
Team dispatch	listen	Despacha uma equipa inteira e suspende-se até que termine
Approval gate	listen	Faz uma pausa para uma decisão de aprovação
For each (map)	forEach	Renderiza um prompt por item e depois despacha o agente uma vez com esses prompts reunidos
Call sub-pipeline	listen	Executa outro modelo como passo aninhado
Clean up worktrees	listen	Remove worktrees isoladas obsoletas; determinístico, não é despachado nenhum agente

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

Ligar os nós entre si

Cada nó de trabalho tem uma porta de saída circular no bordo direito. Arraste dessa porta para outro nó para os ligar. Os disparadores iniciais são iguais: cada um tem a sua própria porta, pelo que uma ligação que sai de Programação também não sai de Execução manual. Prima Adicionar passo (+) logo a seguir a um nó para inserir um tipo a seguir a ele. Passe o cursor pelo ponto médio de uma aresta existente e prima × para a desligar.

As conexões também se editam a partir do nó que as recebe:

1. Selecione o nó a jusante. O respetivo painel de configuração abre à direita.
2. Desloque-se até Gatilhos de e toque no chip de cada nó a montante a que este deva escutar. Tocar num chip selecionado remove a conexão.
3. Se um nó a montante for um router, aparece um bloco Chaves de rota por baixo dos chips com um campo Chave de rota de <node> por cada aresta do router. Introduza a chave com que essa aresta dispara — true ou false nos routers de existência de ficheiros, ou o nome do caso num comutador.

Cada nó disparador é 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 tem de permanecer acíclico — nada no editor o impede de ligar um ciclo, por isso verifique o seu trabalho.

O sentinela terminal é filtrado do canvas, pelo que não pode ser selecionado. O editor volta a ligá-lo a todos os sumidouros alcançáveis sempre que o grafo muda, para que o trabalho que ligar depois do Step pré-preenchido continue a ser executado. Um grafo vazio (um disparador sem sucessores de trabalho) lista o próprio disparador para que uma execução termine imediatamente.

Configurar um nó

Selecione um nó para abrir o respetivo painel de configuração. Os campos que aparecem dependem do corpo do nó.

Todos os nós têm Rótulo, Chaves de entrada (separadas por vírgula) (chaves de estado 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). Os nós de tipo listen e join também podem alternar o seu Tipo entre ambos.

Open conversation

Adiciona um seletor de âmbito de repos (que 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á ativada, um campo Título da conversa dá nome ao fluxo com que a sala abre. Os nós de agente juntam-se a esta sala — não abrem uma própria.

Agente de prompt

Adiciona Agente (que 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 em segundos — 900000 são 15 minutos. Introduzir 900 dá ao passo 0,9 segundos.

O modo de conversa sob o qual um nó de agente de prompt é executado não tem nenhum campo no editor do nó de agente. Vem de extras['mode'] (chat, plan ou review) no nó Open conversation que criou a sala (predefinição review). Defini-lo num passo 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:

• Todos os passos bash de uma execução partilham o cwd <cc_root>/pipelines/<runId>/.
• GITHUB_TOKEN é injetado a partir do armazém de credenciais, pelo que gh e git clone https://x-access-token:$GITHUB_TOKEN@… funcionam sem qualquer configuração.
• O script é lançado como o executável literal bash, pelo que bash tem de estar no PATH do anfitrião do servidor. É uma consideração do Windows.

Router

Um router avalia uma condição e devolve uma chave de rota; o motor só ativa a aresta a jusante cuja chave de rota corresponde e marca os outros ramos como ignorados.

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

• Ficheiro(s) existe(m) — algum — encaminha "true" quando existe qualquer um dos caminhos indicados.
• Ficheiros existem — todos — encaminha "true" apenas quando existem todos os caminhos indicados.
• Comparação — compara um valor de estado com um literal.
• Comutador — encaminha com base no valor de uma chave de estado, com um caso predefinido.

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

O corpo suporta grupos booleanos and / or / not, mas estes não podem ser criados a partir deste formulário — precisam de uma árvore de predicados escrita à mão em extras.predicate. O vocabulário completo de predicados e operadores está na referência de tipos de passo de pipeline.

Join

Não tem configuração própria: espera por todos os seus passos a montante.

Approval gate

O portão despacha o agente aprovador para uma conversa oculta com o prompt do portão e suspende-se. O aprovador procura a sua decisão na conversa e submete-a com submit_output como { "decision": "approved" | "rejected", "reason": "..." }. A decisão fica na chave de saída (predefinição approval_decision), pelo que um router de comutador a jusante pode ramificar a partir dela.

Defina Agente como o aprovador e Prompt como a pergunta do portão. O portão resolve-se através de submit_output como { "decision": "approved" | "rejected", "reason": "..." }. Os nós Reviewer (prompt) submetem da mesma forma.

Team dispatch

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

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

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

For each e Call sub-pipeline

For each itera sobre a chave de estado items por predefinição (extras.iterableKey / extras.itemKey no nó). Renderiza o seu prompt uma vez por item ({{item}} por predefinição) e despacha o agente uma vez com esses prompts concatenados. Uma coleção vazia conclui de imediato com uma lista vazia. Não é um despacho paralelo por item.

Call sub-pipeline suspende-se até que a execução filha alcance um estado terminal e, em seguida, funde o estado final da filha sob a chave de saída (predefinição subflow_result). Aponte-o para uma filha com extras.templateId. Um modelo não pode chamar-se a si próprio; uma filha falhada ou cancelada faz falhar o passo pai, que depois alimenta a política de novas tentativas e de continuar em caso de falha desse passo.

Declarar entradas e permitir execuções manuais

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

1. Prima Execução manual.
2. Ative Permitir execução manual. Este interruptor é guardado de imediato — cria (ou elimina) a linha de disparador manual que faz o modelo aparecer no lançador de execuções.
3. Defina Execuções paralelas máx. se quiser um limite (deixe vazio para ilimitado). Os inícios adicionais esperam no estado queued até que vagar um lugar.
4. Prima Adicionar entrada por cada campo de formulário que uma execução manual deva recolher:

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

Uma entrada Repositório renderiza um seletor sobre 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. Prima Guardar na caixa de diálogo. As edições das entradas são incorporadas no rascunho; são conservadas quando guardar o modelo.

Guardar e ativar

1. Prima Guardar no cabeçalho do editor. Até o fazer, o cabeçalho mostra «Alterações não guardadas».
2. Volte a Definições → Espaço de trabalho → Modelos de pipeline e verifique se o interruptor da linha do modelo está ativado. O motor recusa-se a iniciar um modelo desativado, e um modelo desativado nunca aparece no lançador de execuções.
3. Para o iniciar automaticamente, arraste um disparador da biblioteca de nós para o canvas — consulte Configurar disparadores de pipeline.

Guias relacionados

• Executar um pipeline manualmente
• Configurar disparadores de pipeline
• Monitorizar execuções de pipeline
• Tipos de passo de pipeline

Conceitos relacionados

• Pipelines