Construa fluxos de trabalho fiáveis – saídas, contextos, gatilhos e transferências entre tarefas

Nesta unidade, você aprenderá:

• Como passar dados através de fluxos de trabalho usando os resultados por etapas e trabalhos

• Como usar contextos do GitHub para configuração e controlo

• Como desenhar fluxos de trabalho com gatilhos seguros e bloqueios defensivos

• Como garantir que os fluxos de trabalho funcionam apenas no contexto correto

• Como construir fluxos de trabalho fiáveis usando dados estruturados e lógica de eventos

A autonomia deve ser desenhada, não assumida

Diferentes tarefas acarretam riscos distintos. Uma boa arquitetura de agentes usa políticas para expressar diferentes níveis de autonomia em vez de aplicar as mesmas regras em todo o lado.

Um modelo simples de autonomia baseado no risco poderia ser assim:

Implementação: aprovações ambientais para execução de alto risco

Os ambientes fornecem um ponto de controlo forte para ações arriscadas, como implantações e acesso a segredos protegidos. Se um ambiente estiver configurado com revisores obrigatórios, um trabalho direcionado para esse ambiente fará uma pausa até que a aprovação seja concedida.

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
    steps:
      - run: echo "Deploying to production..."

Este design permite ao agente preparar alterações enquanto impede que execute ações que impactam a produção de forma independente.

Os outputs são contratos de fluxo de trabalho (outputs de etapas vs outputs de trabalhos vs ambiente)

Quando um fluxo de trabalho gera informação que passos posteriores ou trabalhos têm de consumir, trate esses dados como uma saída explícita em vez de "apenas registos".

Ensine e aplique estes princípios:

• As saídas dos passos transmitem valores entre passos na mesma tarefa.

• Os resultados do trabalho transferem valores entre tarefas (através de dependências de tarefas).

• As variáveis de ambiente configuram o comportamento em tempo de execução, mas não devem substituir as saídas para o fluxo de dados estruturados.

Padrão ilustrativo (demonstrações apresentadas, mas sem formato de exame)

- id: generate_plan
  run: |
    echo "plan=high level steps..." >> "$GITHUB_OUTPUT"

- run: |
    echo "Plan: ${{ steps.generate_plan.outputs.plan }}"

Para partilha entre tarefas, publique um resultado de trabalho e faça referência a ele a partir de um trabalho dependente:

jobs:
  plan:
    outputs:
      plan: ${{ steps.generate_plan.outputs.plan }}
    steps:
      - id: generate_plan
        run: echo "plan=..." >> "$GITHUB_OUTPUT"

  implement:
    needs: plan
    steps:
      - run: echo "Using plan: ${{ needs.plan.outputs.plan }}"

Contextos: GitHub vs vars vs ambiente

Use o contexto certo para o propósito certo:

• GitHub.* → metadados de eventos e decisões em tempo de execução ("O que desencadeou esta execução?")

• vars.* → valores de configuração geridos centralmente, concebidos para serem reutilizados

• env.* → variáveis de ambiente ao nível do trabalho e configuração em tempo de execução

Ativação segura e filtragem defensiva

Mesmo quando os fluxos de trabalho são desenhados para PRs, os repositórios frequentemente têm múltiplos gatilhos. Adicione bloqueios defensivos para que o comportamento "apenas PR" não apareça acidentalmente sem contexto PR.

Padrão geral a ensinar:

• Use condições a nível de trabalho para garantir que as ações dependentes de PR só sejam executadas quando a execução estiver ligada a um evento PR.

Bloqueio defensivo para comportamento apenas de pull requests

Mesmo que um fluxo de trabalho seja pensado para ser executado apenas para pull requests, pode ainda assim ser desencadeado por outros eventos (por exemplo, push, workflow_dispatch ou agendamento). Sem salvaguardas adicionais, passos específicos de RP — como comentar um pull request ou avaliar alterações — podem falhar ou comportar-se de forma inesperada.

Pode evitar isto adicionando uma condição ao nível do trabalho que garanta que o fluxo de trabalho só corre quando está associado a um pull request.

name: PR Validation

on:
  pull_request:
    branches: [ main ]
  workflow_dispatch: # allows manual runs, but still gated below

jobs:
  validate-pr:
    # Defensive gating: only run if this is actually a PR context
    if: github.event_name == 'pull_request'

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        run: npm test

      - name: Comment on PR
        run: echo "Validation complete"

Conclusão chave: A fiabilidade do fluxo de trabalho melhora quando planos e sinais são tratados como saídas estruturadas e protegidos por lógica consciente de eventos.

De seguida, irá operar os agentes em segurança, tornando as execuções auditáveis, controlando ferramentas e segredos, e construindo rails de proteção baseados em ganchos e padrões de fiabilidade.