🐙
GitHub Actions 치트시트

CI/CD 워크플로우 YAML 구조, 이벤트 트리거(push/PR/cron/dispatch), Matrix 빌드, Secrets & 환경변수, 캐싱 & 아티팩트, 권한(Permissions) 및 실전 배포 템플릿 완벽 가이드
#github-actions#cicd#devops#workflow#automation#runner#yaml#deployment최종 업데이트: 2026-10-01
GitHub Actions 치트시트 핵심 명령어 및 실전 가이드

## 1. 워크플로우 기본 구조 & 디렉토리 규격
```yaml
# 📁 저장소 루트 기준 .github/workflows/ci.yml 파일 위치
name: Main CI/CD Pipeline

# ⚡ [1] 트리거 이벤트 정의
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

# ⚙️ [2] 실행 작업(Job) 목록 정의
jobs:
  build-and-test:
    name: Build & Unit Test
    runs-on: ubuntu-latest  # 실행 Runner 환경 (ubuntu / windows / macos)
    timeout-minutes: 15     # 작업 최대 실행 시간 제한 (무한 대기 방지)

    steps:
      # 📦 저장소 코드 체크아웃 (필수 첫 단계)
      - name: Checkout Source Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 1    # 최신 커밋 1개만 얕은 복제(Shallow Clone)하여 속도 최적화

      # 🛠️ 런타임 환경 설정
      - name: Setup Node.js Runtime
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'      # 패키지 의존성 자동 캐싱

      # 💻 쉘 명령어 실행
      - name: Install & Run Tests
        run: |
          npm ci
          npm run test:ci
          npm run build
```
워크플로우 파일은 반드시 프로젝트 최상위의 `.github/workflows/` 디렉토리 내에 `.yml` 또는 `.yaml` 확장자로 위치해야 합니다.

## 2. 이벤트 트리거 & 필터링 (Event Triggers)
```yaml
on:
  # 🔀 [1] 브랜치 및 태그 푸시 필터링
  push:
    branches:
      - main
      - 'releases/**'      # releases/v1.0 등 와일드카드 매칭
    branches-ignore:
      - 'docs/**'          # 특정 브랜치 패턴 제외
    tags:
      - 'v*.*.*'           # v1.0.0 형태의 Git 릴리즈 태그 생성 시만 트리거
    paths:
      - 'src/**'           # src 폴더 변경 시에만 실행 (docs, readme 변경 시 생략)
      - 'package.json'
    paths-ignore:
      - '**.md'

  # 📥 [2] 풀 리퀘스트(PR) 세부 액션 필터링
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    branches: [main]

  # ⏲️ [3] CRON 정기 스케줄러 (UTC 기준)
  schedule:
    - cron: '0 0 * * 1-5'  # 월~금 한국시간 오전 9시(UTC 00:00) 매일 자동 실행

  # 🎛️ [4] GitHub 웹 UI 수동 실행 버튼 (파라미터 입력 지원)
  workflow_dispatch:
    inputs:
      target_env:
        description: '배포 대상 환경'
        required: true
        default: 'staging'
        type: choice
        options: [staging, production]
      deploy_tag:
        description: '배포할 태그 버전'
        required: false
        type: string
```
`paths` 필터를 활용하면 문서(`.md`) 수정이나 CI와 무관한 파일 변경 시 불필요한 빌드 리소스 낭비를 효과적으로 방지할 수 있습니다.

## 3. 환경변수(Env), Contexts & 암호화 Secrets
```yaml
env:
  GLOBAL_STAGE: 'production' # 전역 환경변수

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      JOB_ENV: 'live'        # 특정 Job 내 환경변수

    steps:
      - name: Print Built-in GitHub Contexts
        run: |
          echo "리포지토리: ${{ github.repository }}"
          echo "트리거 브랜치: ${{ github.ref_name }}"
          echo "커밋 SHA: ${{ github.sha }}"
          echo "실행자: ${{ github.actor }}"
          echo "빌드 번호: #${{ github.run_number }}"

      # 🔒 저장소 Secrets 및 전역 환경변수 주입
      - name: Deploy with Secret Token
        env:
          DB_PASSWORD: ${{ secrets.PROD_DB_PASSWORD }} # Settings > Secrets에서 등록
          API_URL: ${{ vars.PUBLIC_API_URL }}          # Settings > Variables에서 등록
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}    # 자동 발급 기본 토큰
        run: |
          ./deploy.sh --token "$DB_PASSWORD" --url "$API_URL"
```
보안 토큰 및 패스워드는 일반 `vars`가 아닌 암호화 저장소인 `secrets`에 등록해야 로그에 마스킹(`***`) 처리됩니다.

## 4. 조건문(if) & 상태 검사 함수 (Conditionals)
```yaml
jobs:
  notify-and-cleanup:
    runs-on: ubuntu-latest
    steps:
      # ✅ [1] 특정 브랜치 또는 이벤트 조건부 실행
      - name: Run Only on Main Branch Push
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        run: echo "Production 배포 단계 실행"

      # ❌ [2] 앞선 Step이 실패했을 때만 실행 (알림 전송 등)
      - name: Send Slack Alert on Failure
        if: failure()
        run: ./send-slack-alert.sh --status "failed"

      # 🔄 [3] 성공/실패 여부와 관계없이 무조건 항상 실행
      - name: Always Cleanup Temporary Files
        if: always()
        run: rm -rf /tmp/build-cache

      # 🛑 [4] 에러가 발생해도 전체 워크플로우를 중단하지 않음
      - name: Optional Lint Check
        continue-on-error: true
        run: npm run lint:lenient
```
`always()`, `failure()`, `success()`, `cancelled()` 상태 함수를 사용하면 이전 단계의 실패 여부에 따라 슬랙/디스코드 장애 알림이나 뒷정리 스크립트를 안정적으로 구동할 수 있습니다.

## 5. Matrix 전략 (병렬 멀티 버전 빌드)
```yaml
jobs:
  cross-test:
    name: Test Node ${{ matrix.node }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false # 하나의 행이 실패해도 다른 버전 테스트를 중단하지 않고 계속 진행
      max-parallel: 4  # 동시 실행 최대 Worker 수 제한
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: [18, 20, 22]
        # ➕ 특정 조합 전용 환경변수/설정 추가 (include)
        include:
          - os: ubuntu-latest
            node: 22
            experimental: true
        # ➖ 특정 조합 제외 (exclude)
        exclude:
          - os: windows-latest
            node: 18

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm test
```
다양한 OS와 런타임 버전 조합을 병렬로 매트릭스 확장하여 크로스 플랫폼 호환성 테스트 시간을 극적으로 단축합니다.

## 6. Job 간 의존성 & 데이터 전달 (Needs & Outputs)
```yaml
jobs:
  # 1단계: 빌드 및 결과값 도출
  build:
    runs-on: ubuntu-latest
    outputs:
      artifact_version: ${{ steps.gen-version.outputs.pkg_ver }}
      image_tag: ${{ steps.gen-version.outputs.img_tag }}
    steps:
      - uses: actions/checkout@v4
      - id: gen-version
        run: |
          VERSION=$(node -p "require('./package.json').version")
          echo "pkg_ver=$VERSION" >> "$GITHUB_OUTPUT"
          echo "img_tag=v${VERSION}-${GITHUB_SHA::7}" >> "$GITHUB_OUTPUT"

  # 2단계: 1단계가 성공한 후 결과값을 받아 배포 실행
  deploy:
    needs: [build] # build Job이 성공해야만 실행됨
    runs-on: ubuntu-latest
    steps:
      - name: Deploy Built Version
        run: |
          echo "배포할 패키지 버전: ${{ needs.build.outputs.artifact_version }}"
          echo "도커 이미지 태그: ${{ needs.build.outputs.image_tag }}"
```
Step 간 출력값은 `echo "키=값" >> "$GITHUB_OUTPUT"`으로 기록하며, Job 간에는 `outputs` 선언 후 `needs.<job_id>.outputs.<key>`로 참조합니다.

## 7. 빌드 캐싱 최적화 (Dependency Caching)
```yaml
jobs:
  build-with-cache:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # ⚡ [1] 범용 actions/cache@v4 활용 (키 기반 복원)
      - name: Cache Node Modules
        uses: actions/cache@v4
        id: npm-cache
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-npm-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-npm-

      # ☕ [2] Gradle 빌드 캐시 (Spring Boot 등)
      - name: Cache Gradle Packages
        uses: actions/cache@v4
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
          restore-keys: |
            ${{ runner.os }}-gradle-

      # 🚀 [3] 셋업 액션 내장 자동 캐시 (가장 권장)
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm' # 또는 'yarn', 'pnpm'

      - run: npm ci
```
`package-lock.json`이나 `build.gradle` 파일의 해시값(`hashFiles`)을 캐시 키로 지정하면 라이브러리 추가가 없을 때 다운로드 시간을 80% 이상 단축할 수 있습니다.

## 8. 빌드 산출물 아티팩트 공유 (Upload & Download)
```yaml
jobs:
  build-app:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build # dist 폴더 생성

      # ⬆️ [1] 산출물 압축 업로드 (Job 간 전달 또는 웹 UI 다운로드용)
      - name: Upload Build Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: production-dist
          path: dist/
          retention-days: 7 # 보관 기간 7일 설정 (저장 공간 절약)

  release-deploy:
    needs: [build-app]
    runs-on: ubuntu-latest
    steps:
      # ⬇️ [2] 이전 Job에서 생성한 아티팩트 다운로드
      - name: Download Build Artifacts
        uses: actions/download-artifact@v4
        with:
          name: production-dist
          path: ./dist

      - name: Check Downloaded Files
        run: ls -la ./dist
```
Job들은 각각 독립된 격리 가상머신에서 실행되므로 파일 시스템을 공유할 수 없습니다. Job 간에 생성된 번들 파일은 `upload-artifact`와 `download-artifact`를 통해 전달해야 합니다.

## 9. 최소 권한 보안 설정 (Permissions)
```yaml
# 🔒 [1] 워크플로우 전체 기본 권한을 읽기 전용으로 제한 (보안 모범 사례)
permissions:
  contents: read

jobs:
  create-release-and-pr:
    runs-on: ubuntu-latest
    # 🔑 [2] 특정 Job에서만 필요한 세부 권한 명시적 부여
    permissions:
      contents: write       # 릴리즈 태그 생성 및 커밋 푸시
      pull-requests: write  # PR에 코멘트 남기기
      issues: write         # 이슈 생성 및 수정
      packages: write       # GHCR (컨테이너 레지스트리) 푸시
      id-token: write       # AWS, GCP OIDC 인증 연동 시 필수

    steps:
      - uses: actions/checkout@v4
      - name: Add PR Comment
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '🚀 CI 빌드 및 테스트 통과 완료!'
            })
```
기본 발급되는 `GITHUB_TOKEN`에 과도한 권한이 주어지는 것을 막기 위해 최상단에 `permissions: { contents: read }`를 두고 필요한 Job에만 쓰기 권한을 부여하는 것이 보안의 핵심입니다.

## 10. 재사용 워크플로우 & 복합 액션 (Reusable Workflows)
```yaml
# 📁 .github/workflows/reusable-deploy.yml (호출될 공통 템플릿)
name: Reusable Deploy Module
on:
  workflow_call:
    inputs:
      target_env:
        required: true
        type: string
    secrets:
      DEPLOY_KEY:
        required: true

jobs:
  run-deploy:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to ${{ inputs.target_env }} with secret key"

# -------------------------------------------------------------
# 📁 .github/workflows/main.yml (호출하는 메인 워크플로우)
jobs:
  call-deploy:
    uses: ./.github/workflows/reusable-deploy.yml
    with:
      target_env: 'production'
    secrets:
      DEPLOY_KEY: ${{ secrets.PROD_SERVER_KEY }}
      # 또는 상위 워크플로우 시크릿 일괄 상속: secrets: inherit
```
`workflow_call`을 사용하면 여러 서비스 리포지토리나 파이프라인에서 중복되는 배포/테스트 로직을 하나의 템플릿 파일로 중앙 관리할 수 있습니다.

## 11. 서비스 컨테이너 통합 테스트 (Docker Services)
```yaml
jobs:
  integration-test:
    runs-on: ubuntu-latest

    # 🐳 Runner 백그라운드에 함께 띄울 서비스 컨테이너 정의
    services:
      postgres:
        image: postgres:15-alpine
        env:
          POSTGRES_DB: test_db
          POSTGRES_USER: test_user
          POSTGRES_PASSWORD: test_password
        ports:
          - 5432:5432
        # 서비스가 완전히 준비될 때까지 대기하는 헬스체크 옵션
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

      redis:
        image: redis:7-alpine
        ports:
          - 6379:6379

    steps:
      - uses: actions/checkout@v4
      - name: Run Integration Tests with Database
        env:
          DB_HOST: localhost
          DB_PORT: 5432
        run: npm run test:e2e
```
`services` 키워드를 사용하면 별도의 외부 클라우드 DB 없이도 실제 PostgreSQL, Redis, MySQL 컨테이너를 가상머신에 띄워 완벽한 엔드투엔드(E2E) 통합 테스트를 수행할 수 있습니다.

## 12. 실전 프로덕션 CI/CD 템플릿 모음
```yaml
# 🚀 [1] Spring Boot (Gradle) 빌드 & 테스트 파이프라인
name: Java Spring CI
on: [push]
jobs:
  spring-ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
          cache: 'gradle'
      - name: Grant Execute Permission for Gradlew
        run: chmod +x gradlew
      - name: Build with Gradle
        run: ./gradlew build -x test --parallel
      - name: Run Unit Tests
        run: ./gradlew test

# 🐳 [2] Docker 이미지 빌드 & GHCR(컨테이너 레지스트리) 푸시
  docker-publish:
    needs: [spring-ci]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ghcr.io/${{ github.repository }}:latest
            ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
```
`temurin` 배포판과 `cache: 'gradle'`, 그리고 Docker의 `type=gha` 캐시 백엔드를 결합하면 엔터프라이즈 환경에서도 2~3분 이내의 초고속 배포 파이프라인을 구축할 수 있습니다.
💬
GitHub Actions 치트시트

의견 및 질문

댓글 수정

댓글 삭제
