표준 워크플로 구문 요소 설명

완료됨

GitHub Actions 워크플로는 자동화가 실행되는 시기, 위치 및 방법을 정의하는 특정 요소와 함께 YAML 구문을 사용합니다. 이러한 핵심 구문 요소를 이해하는 것은 효과적인 워크플로를 만드는 데 필수적입니다.

필수 워크플로 요소

최상위 워크플로 구성

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

핵심 구문 요소 설명

요소	목적	필수	예시
name	GitHub UI의 워크플로 표시 이름	선택적	name: "Build and Test"
on	워크플로 실행을 위한 이벤트 트리거	필수	on: [push, pull_request]
jobs	실행할 작업 컬렉션	필수	jobs: build: ...
runs-on	실행기 환경을 지정합니다.	필수	runs-on: ubuntu-latest
steps	작업 내의 순차 작업	필수	steps: - name: ...
uses	미리 빌드된 작업을 참조합니다.	선택적	uses: actions/checkout@v4
run	셸 명령을 실행합니다.	선택적	run: npm test

전체 워크플로 예제

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

고급 구문 요소

조건부 실행

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

행렬 전략

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

재사용 가능한 워크플로

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

워크플로 구문에 대한 모범 사례

구조 및 조직

• 워크플로, 작업 및 단계에 설명이 포함된 이름 사용
• 작업 내에서 논리적으로 관련 단계 그룹화
• 워크플로를 특정 목적(CI, CD, 유지 관리)에 집중

효율성 최적화

• paths 및 paths-ignore을 사용하여 불필요한 실행을 제한하십시오.
• actions/cache 또는 기본 제공 캐싱을 사용하여 종속성을 캐시하십시오.
• 병렬로 독립 작업 실행

보안 고려 사항

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

오류 처리 및 디버깅

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"

포괄적인 구문 설명서는 GitHub Actions 참조에 대한 공식 워크플로 구문을 참조하세요.