Criar fluxos de trabalho confiáveis – resultados, contextos, gatilhos e transferências entre tarefas

Nesta unidade, você aprenderá:

• Como passar dados por fluxos de trabalho usando saídas de etapas e tarefas

• Como usar GitHub contextos para configuração e controle

• Como projetar fluxos de trabalho com gatilhos seguros e barreiras defensivas

• Como garantir que os fluxos de trabalho só são executados no contexto correto

• Como criar fluxos de trabalho confiáveis usando dados estruturados e lógica de evento

A autonomia deve ser projetada, não assumida

Tarefas diferentes têm riscos diferentes. Uma boa arquitetura de agente usa a política para expressar diferentes níveis de autonomia em vez de aplicar as mesmas regras em todos os lugares.

Um modelo de autonomia simples baseado em risco pode ter esta aparência:

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

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

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

Esse design permite que o agente prepare as alterações, impedindo que ele execute ações que afetam a produção de forma independente.

Os resultados são contratos de fluxo de trabalho (resultados de etapa vs. resultados de tarefa vs. ambiente)

Quando um fluxo de trabalho gera informações que as etapas ou tarefas subsequentes precisam utilizar, trate esses dados como uma saída explícita, e não como “apenas logs”.

Ensinar e aplicar estes princípios:

• As saídas das etapas transmitem valores entre as etapas de um mesmo trabalho.

• Os resultados de trabalhos transmitem valores entre trabalhos (por meio de dependências entre trabalhos).

• As variáveis de ambiente configuram o comportamento de runtime, mas não devem substituir as saídas para o fluxo de dados estruturado.

Padrão ilustrativo (com mecânica apresentada, mas não no formato de exame):

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

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

Para compartilhar resultados entre tarefas, publique o resultado de uma tarefa e faça referência a ele em uma tarefa 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 env

Use o contexto certo para a finalidade certa:

• github.* → metadados de evento e decisões de runtime ("o que disparou essa execução?")

• vars.* → valores de configuração gerenciados centralmente projetados para serem reutilizados

• env.* → variáveis de ambiente no nível do trabalho e configuração de runtime

Gatilho seguro e bloqueio defensivo

Mesmo quando os fluxos de trabalho são projetados para PRs, os repositórios geralmente têm vários gatilhos. Adicione um mecanismo de verificação de segurança para que o comportamento "somente PR" não seja executado acidentalmente sem um contexto de PR.

Padrão geral a ser ensinado:

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

Controle de acesso defensivo para comportamento restrito a solicitações de pull

Mesmo que um fluxo de trabalho seja executado apenas para solicitações de pull, ele ainda poderá ser disparado por outros eventos (por exemplo, push, workflow_dispatch ou agendamento). Sem proteções adicionais, etapas específicas de PR, como comentar uma solicitação de pull ou avaliar alterações, podem falhar ou se comportar inesperadamente.

Você pode evitar isso adicionando uma condição de nível de trabalho que garante que o fluxo de trabalho seja executado somente quando ele estiver associado a uma solicitação de pull.

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"

Principal conclusão: a confiabilidade do fluxo de trabalho melhora quando os planos e sinais são tratados como saídas estruturadas e protegidos por lógica sensível a eventos.

Em seguida, você operará os agentes com segurança, tornando as execuções auditáveis, controlando ferramentas e segredos e criando barreiras de proteção e padrões de confiabilidade baseados em hooks.