Descripción de los elementos de sintaxis de flujo de trabajo estándar

  • 2 minutos

Los flujos de trabajo de Acciones de GitHub usan la sintaxis YAML con elementos específicos que definen cuándo, dónde y cómo se ejecuta la automatización. Comprender estos elementos de sintaxis principales es esencial para crear flujos de trabajo eficaces.

Elementos esenciales del flujo de trabajo

Configuración de flujo de trabajo de nivel 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 sintaxis principales explicados

Elemento Propósito Obligatorio Example
name Nombre visible del flujo de trabajo en la interfaz de usuario de GitHub Opcional name: "Build and Test"
on Desencadenadores de eventos para la ejecución del flujo de trabajo Required on: [push, pull_request]
jobs Colección de trabajos para ejecutar Required jobs: build: ...
runs-on Especifica el entorno de ejecución Required runs-on: ubuntu-latest
steps Acciones secuenciales dentro de un trabajo Required steps: - name: ...
uses Referencias a acciones pregeneradas Opcional uses: actions/checkout@v4
run Ejecuta comandos de shell Opcional run: npm test

Ejemplo de flujo de trabajo 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 sintaxis avanzada

Ejecución 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

Estrategias 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 }}

Flujos de trabajo reutilizables

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

Procedimientos recomendados para la sintaxis de flujo de trabajo

Estructura y organización

  • Uso de nombres descriptivos para flujos de trabajo, trabajos y pasos
  • Agrupar los pasos relacionados lógicamente dentro de los trabajos
  • Mantener los flujos de trabajo centrados en propósitos específicos (CI, CD, mantenimiento)

Optimización de la eficiencia

  • Uso paths y paths-ignore para limitar ejecuciones innecesarias
  • Cachar las dependencias con actions/cache o caché integrado
  • Ejecución de trabajos independientes en paralelo

Consideraciones de seguridad

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 }}

Gestión y depuración de errores

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 obtener documentación completa sobre la sintaxis, consulte la referencia oficial de la sintaxis de flujo de trabajo para Acciones de GitHub .