Beschreiben von Standardsyntaxelementen für Workflows

  • 2 Minuten

GitHub Actions-Workflows verwenden YAML-Syntax mit bestimmten Elementen, die definieren, wann, wo und wie Ihre Automatisierung ausgeführt wird. Das Verständnis dieser Kernsyntaxelemente ist für die Erstellung effektiver Workflows unerlässlich.

Wesentliche Workflowelemente

Workflowkonfiguration auf oberster Ebene

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

Erläuterte Kernsyntaxelemente

Element Zweck Erforderlich Example
name Anzeigename des Workflows in der GitHub-Benutzeroberfläche Wahlfrei name: "Build and Test"
on Ereignistrigger für die Workflowausführung Erforderlich on: [push, pull_request]
jobs Sammlung von auszuführenden Aufträgen Erforderlich jobs: build: ...
runs-on Gibt die Runner-Umgebung an. Erforderlich runs-on: ubuntu-latest
steps Sequenzielle Aktionen innerhalb eines Auftrags Erforderlich steps: - name: ...
uses Verweisen auf vordefinierte Aktionen Wahlfrei uses: actions/checkout@v4
run Führt Shellbefehle aus Wahlfrei run: npm test

Vollständiges Workflowbeispiel

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

Erweiterte Syntaxelemente

Bedingte Ausführung

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

Matrixstrategien

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

Wiederverwendbare Workflows

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

Bewährte Methoden für die Workflowsyntax

Struktur und Organisation

  • Verwenden aussagekräftiger Namen für Workflows, Aufträge und Schritte
  • Gruppieren verwandter Schritte logisch innerhalb von Aufträgen
  • Workflows auf bestimmte Zwecke konzentrieren (CI, CD, Wartung)

Effizienzoptimierung

  • Verwenden Sie paths und paths-ignore, um unnötige Läufe zu begrenzen
  • Cacheabhängigkeiten mit actions/cache oder integriertem Zwischenspeichern
  • Parallele Ausführung unabhängiger Aufträge

Sicherheitsüberlegungen

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

Fehlerbehandlung und Debugging

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"

Eine umfassende Syntaxdokumentation finden Sie im offiziellen Referenzdokument für die Workflowsyntax von GitHub-Aktionen.