GitHub Actions으로 CI/CD 입문

들어가며

GitHub Actions를 이전에 몇 번 써봤는데 yml 파일 구조를 정확히 이해하지 못하고 복붙해서 쓰는 수준이었다.
핵심 개념과 구조를 제대로 정리해둔다.

---

GitHub Actions란?

GitHub 저장소에서 특정 이벤트가 발생했을 때 자동으로 워크플로우를 실행하는 CI/CD 플랫폼이다.
별도 서버 없이 GitHub 안에서 빌드, 테스트, 배포를 자동화할 수 있다.

---

핵심 개념

개념	설명
Workflow	자동화된 프로세스 전체. .github/workflows/*.yml에 정의
Event	워크플로우를 트리거하는 조건 (push, PR, schedule 등)
Job	워크플로우 안의 작업 단위. 각 Job은 독립된 Runner에서 실행
Step	Job 안의 개별 실행 단계
Action	재사용 가능한 Step 단위
Runner	Job이 실행되는 서버 환경 (GitHub 제공 또는 self-hosted)

---

기본 구조

# .github/workflows/ci.yml

name: CI

on:                          # 트리거 이벤트
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:                     # Job 이름
    runs-on: ubuntu-latest   # Runner 환경

    steps:
      - name: 코드 체크아웃
        uses: actions/checkout@v4

      - name: Node.js 설정
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: 의존성 설치
        run: npm ci

      - name: 테스트 실행
        run: npm test

---

주요 트리거 이벤트

on:
  # push 시 실행
  push:
    branches: [ main, develop ]
    paths:
      - 'src/**'           # 특정 경로 변경 시만 실행

  # PR 시 실행
  pull_request:
    branches: [ main ]
    types: [ opened, synchronize, reopened ]

  # 스케줄 실행 (매일 오전 9시 UTC)
  schedule:
    - cron: '0 9 * * *'

  # 수동 실행
  workflow_dispatch:
    inputs:
      environment:
        description: '배포 환경'
        required: true
        default: 'staging'

---

실전 예시

Node.js CI

name: Node.js CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18, 20, 22]   # 여러 버전 병렬 테스트

    steps:
      - uses: actions/checkout@v4

      - name: Node.js ${{ matrix.node-version }} 설정
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'

      - run: npm ci
      - run: npm run build
      - run: npm test

자동 배포 (main push 시)

name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: 빌드
        run: npm ci && npm run build

      - name: S3 배포
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          aws s3 sync ./dist s3://my-bucket --delete

---

환경 변수와 Secrets

민감한 정보는 코드에 직접 넣지 않고 GitHub Secrets에 저장한다.

저장소 → Settings → Secrets and variables → Actions → New repository secret

steps:
  - name: 환경 변수 사용
    env:
      API_KEY: ${{ secrets.API_KEY }}
      NODE_ENV: production
    run: echo "배포 시작"

---

Job 간 의존성

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  deploy:
    runs-on: ubuntu-latest
    needs: test          # test Job이 성공해야 실행
    steps:
      - run: npm run deploy

---

캐시 활용

의존성을 매번 설치하면 시간이 오래 걸린다. cache 옵션으로 속도를 개선할 수 있다.

- name: Node.js 설정
  uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'          # node_modules 캐시

---

정리

개념	설명
.github/workflows/*.yml	워크플로우 정의 파일 위치
on	트리거 이벤트 설정
jobs	실행할 작업 목록
runs-on	Runner 환경 지정
uses	미리 만들어진 Action 사용
run	직접 실행할 명령어
secrets	민감한 정보 저장소
needs	Job 간 의존성 설정