Descrever elementos de sintaxe de fluxo de trabalho padrão

  • 2 minutos

Os fluxos de trabalho do GitHub Actions usam a sintaxe YAML com elementos específicos que definem quando, onde e como a automação é executada. Entender esses elementos de sintaxe principal é essencial para criar fluxos de trabalho eficazes.

Elementos de fluxo de trabalho essenciais

Configuração de fluxo de trabalho de nível superior

name: CI/CD Pipeline # Workflow name (optional but recommended)
on: # Event triggers
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: "0 2 * * 1" # Weekly Monday 2 AM UTC

jobs:# Job definitions
  # Job configurations go here

Elementos de sintaxe principal explicados

Elemento Propósito Obrigatório Example
name Nome de exibição do fluxo de trabalho na interface do usuário do GitHub Opcional name: "Build and Test"
on Gatilhos de evento para execução de fluxo de trabalho Required on: [push, pull_request]
jobs Coleção de trabalhos a serem executados Required jobs: build: ...
runs-on Especifica o ambiente do executor Required runs-on: ubuntu-latest
steps Ações sequenciais em um trabalho Required steps: - name: ...
uses Faz referência a ações pré-construídas Opcional uses: actions/checkout@v4
run Executa comandos de shell Opcional run: npm test

Exemplo de fluxo de trabalho completo

name: Node.js CI/CD Pipeline

# Event configuration
on:
  push:
    branches: [main, develop]
    paths-ignore: ["docs/**", "*.md"]
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

# Environment variables (workflow-level)
env:
  NODE_VERSION: "20"
  CI: true

# Job definitions
jobs:
  # Test job
  test:
    name: Run Tests
    runs-on: ubuntu-latest

    # Job-level environment variables
    env:
      DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }}

    # Job steps
    steps:
      - name: Check out code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: "npm"

      - name: Install dependencies
        run: |
          npm ci
          npm audit --audit-level=high

      - name: Run tests
        run: |
          npm run test:coverage
          npm run test:integration
        env:
          NODE_ENV: test

      - name: Upload coverage reports
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage-reports
          path: coverage/
          retention-days: 30

  # Build job (depends on test)
  build:
    name: Build Application
    needs: test
    runs-on: ubuntu-latest

    outputs:
      build-version: ${{ steps.version.outputs.version }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: "npm"

      - name: Install and build
        run: |
          npm ci --production
          npm run build

      - name: Generate version
        id: version
        run: |
          VERSION=$(date +%Y%m%d)-${GITHUB_SHA::8}
          echo "version=$VERSION" >> $GITHUB_OUTPUT

      - name: Save build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build-${{ steps.version.outputs.version }}
          path: |
            dist/
            package.json

Elementos de sintaxe avançados

Execução condicional

steps:
  - name: Deploy to production
    if: github.ref == 'refs/heads/main' && success()
    run: ./deploy.sh

  - name: Notify on failure
    if: failure()
    run: ./notify-failure.sh

Estratégias de matriz

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18, 20, 22]
        include:
          - os: ubuntu-latest
            node-version: 22
            experimental: true
      fail-fast: false
    runs-on: ${{ matrix.os }}

Fluxos de trabalho reutilizáveis

jobs:
  call-reusable-workflow:
    uses: ./.github/workflows/reusable-tests.yml
    with:
      environment: production
      node-version: "20"
    secrets:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}

Práticas recomendadas para sintaxe de fluxo de trabalho

Estrutura e organização

  • Usar nomes descritivos para fluxos de trabalho, trabalhos e etapas
  • Agrupar etapas relacionadas logicamente em trabalhos
  • Manter os fluxos de trabalho focados em finalidades específicas (CI, CD, manutenção)

Otimização de eficiência

  • Usar paths e paths-ignore para limitar execuções desnecessárias
  • Armazenar dependências em cache com actions/cache ou com cache integrado
  • Executar trabalhos independentes em paralelo

Considerações de segurança

permissions:
  contents: read
  security-events: write
  pull-requests: write

env:
  # Use secrets for sensitive data
  API_KEY: ${{ secrets.API_KEY }}
  # Use variables for non-sensitive configuration
  ENVIRONMENT: ${{ vars.ENVIRONMENT }}

Tratamento e depuração de erros

steps:
  - name: Debug information
    if: env.ACTIONS_STEP_DEBUG == 'true'
    run: |
      echo "Runner OS: $RUNNER_OS"
      echo "Workflow: $GITHUB_WORKFLOW"
      echo "Event: $GITHUB_EVENT_NAME"

Para uma documentação abrangente da sintaxe, consulte a referência oficial de sintaxe de fluxo de trabalho do GitHub Actions.