GitHub Actions CI/CD 완벽 가이드

GitHub Actions를 활용한 CI/CD 파이프라인 구축 방법을 기초부터 심화까지 다룹니다. 워크플로우 작성, 이벤트 트리거, 환경 변수, 시크릿 관리, 매트릭스 빌드 등 실무에 필요한 모든 내용을 포함합니다.

---

---

들어가며

이 글에서는 GitHub Actions CI/CD 완벽 가이드에 대해 상세히 알아보겠습니다. 총 12가지 주요 개념을 다루며, 각각의 개념에 대한 설명과 실제 코드 예제를 함께 제공합니다.

목차

1. 기본_워크플로우_구조
2. 특정_브랜치_이벤트_트리거
3. 환경_변수와_시크릿_관리
4. 매트릭스_빌드_전략
5. 조건부_실행과_Job_의존성
6. 캐싱으로_빌드_속도_향상
7. 재사용_가능한_워크플로우
8. 커스텀_액션_생성
9. 아티팩트_업로드와_다운로드
10. 컨테이너_서비스_활용
11. 동적_환경_배포
12. 스케줄_기반_워크플로우

---

1. 기본 워크플로우 구조

개요

GitHub Actions의 가장 기본적인 워크플로우 파일 구조입니다. 이벤트 트리거, 작업(jobs), 단계(steps)로 구성됩니다.

코드 예제

name: Basic CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install
      - run: npm test

설명

push와 pull_request 이벤트가 발생하면 자동으로 코드를 체크아웃하고, 의존성을 설치한 후 테스트를 실행합니다.

---

2. 특정 브랜치 이벤트 트리거

개요

특정 브랜치나 경로에서만 워크플로우를 실행하도록 필터링할 수 있습니다.

코드 예제

on:
  push:
    branches: [main, develop]
    paths:
      - 'src/**'
      - '!src/test/**'
  pull_request:
    branches: [main]

설명

main과 develop 브랜치의 push 이벤트 중 src 폴더(테스트 제외)에 변경사항이 있을 때만 실행됩니다.

---

3. 환경 변수와 시크릿 관리

개요

워크플로우에서 환경 변수와 GitHub Secrets를 안전하게 사용하는 방법입니다.

코드 예제

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      NODE_ENV: production
    steps:
      - run: echo "API=${{ secrets.API_KEY }}" >> .env
      - run: npm run build
      - run: npm run deploy

설명

환경 변수는 env로 설정하고, API 키 같은 민감한 정보는 GitHub Secrets를 통해 안전하게 관리합니다.

---

4. 매트릭스 빌드 전략

개요

여러 버전의 Node.js나 운영체제에서 동시에 테스트를 실행할 수 있습니다.

코드 예제

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [16, 18, 20]
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}

설명

Ubuntu와 Windows에서 Node.js 16, 18, 20 버전으로 총 6가지 조합을 동시에 테스트합니다.

---

5. 조건부 실행과 Job 의존성

개요

특정 조건에서만 작업을 실행하거나, 다른 작업의 완료를 기다릴 수 있습니다.

코드 예제

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test
  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: npm run deploy

설명

test 작업이 성공적으로 완료되고, main 브랜치일 때만 deploy 작업이 실행됩니다.

---

6. 캐싱으로 빌드 속도 향상

개요

npm, yarn, pip 등의 의존성을 캐싱하여 워크플로우 실행 시간을 크게 단축시킵니다.

코드 예제

steps:
  - uses: actions/checkout@v3
  - uses: actions/cache@v3
    with:
      path: ~/.npm
      key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
  - run: npm ci
  - run: npm test

설명

package-lock.json의 해시값을 키로 사용하여 npm 캐시를 저장하고 재사용합니다.

---

7. 재사용 가능한 워크플로우

개요

여러 리포지토리에서 공통으로 사용할 수 있는 재사용 가능한 워크플로우를 만들 수 있습니다.

코드 예제

# .github/workflows/reusable.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: true
        type: string
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v3
        with:
          node-version: ${{ inputs.node-version }}

설명

workflow_call 이벤트로 다른 워크플로우에서 호출할 수 있으며, 입력 파라미터를 받을 수 있습니다.

---

8. 커스텀 액션 생성

개요

JavaScript로 자신만의 GitHub Action을 만들어 워크플로우에서 재사용할 수 있습니다.

코드 예제

// action.yml
name: 'Custom Action'
inputs:
  message:
    required: true
runs:
  using: 'node20'
  main: 'index.js'

// index.js
const core = require('@actions/core');
const message = core.getInput('message');
console.log(message);

설명

@actions/core 패키지를 사용하여 입력값을 받고 처리하는 커스텀 액션을 만들 수 있습니다.

---

9. 아티팩트 업로드와 다운로드

개요

빌드 결과물이나 테스트 리포트를 아티팩트로 저장하고 다른 작업에서 사용할 수 있습니다.

코드 예제

jobs:
  build:
    steps:
      - run: npm run build
      - uses: actions/upload-artifact@v3
        with:
          name: dist
          path: dist/
  deploy:
    needs: build
    steps:
      - uses: actions/download-artifact@v3
        with:
          name: dist

설명

build 작업에서 생성된 dist 폴더를 아티팩트로 업로드하고, deploy 작업에서 다운로드하여 사용합니다.

---

10. 컨테이너 서비스 활용

개요

데이터베이스나 Redis 같은 서비스를 Docker 컨테이너로 실행하여 테스트할 수 있습니다.

코드 예제

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
    steps:
      - run: npm test

설명

PostgreSQL 컨테이너를 서비스로 실행하고, 헬스체크를 통해 준비가 완료되면 테스트를 실행합니다.

---

11. 동적 환경 배포

개요

GitHub Environments를 활용하여 승인 프로세스와 함께 프로덕션에 배포할 수 있습니다.

코드 예제

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - uses: actions/checkout@v3
      - run: npm run deploy
      - run: echo "DEPLOY_URL=${{ vars.DEPLOY_URL }}" >> $GITHUB_OUTPUT

설명

production 환경에 배포하며, 환경별 변수와 승인 규칙을 설정할 수 있습니다.

---

12. 스케줄 기반 워크플로우

개요

Cron 표현식을 사용하여 정기적으로 워크플로우를 실행할 수 있습니다.

코드 예제

on:
  schedule:
    - cron: '0 2 * * 1-5'
  workflow_dispatch:

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - run: npm run backup
      - run: npm run cleanup

설명

매주 월요일부터 금요일까지 새벽 2시에 자동으로 백업을 실행하며, workflow_dispatch로 수동 실행도 가능합니다.

---

마치며

이번 글에서는 GitHub Actions CI/CD 완벽 가이드에 대해 알아보았습니다. 총 12가지 개념을 다루었으며, 각각의 사용법과 예제를 살펴보았습니다.

관련 태그

#GitHub #CI/CD #Workflows #Actions #Automation