GitHub Actions로 CI/CD 파이프라인 만들기

GitHub Actions로 CI/CD 파이프라인 만들기 — 빌드부터 배포까지. 코드를 push하면 알아서 테스트하고, 이미지를 빌드해 올리고, 배포까지 한다. 손으로 하던 배포를 자동화하는 GitHub Actions를, 워크플로 구조부터 실제 .yml과 실행 결과까지 한 번에 정리한다.

---

들어가며

Docker 입문 글에서 애플리케이션을 이미지로 만들고 컨테이너로 실행하는 법을 다뤘다. 그리고 마지막에 이렇게 적었다 — "다음 단계는 이 이미지를 자동으로 빌드·배포하는 CI/CD"라고. 그 다음 단계가 이 글이다.

이미지를 만들 줄 알게 됐어도, 매번 손으로 하면 이렇게 흘러간다. 코드를 고치고, 로컬에서 테스트하고(가끔 깜빡하고), docker build 치고, 레지스트리에 push하고, 서버에 SSH로 들어가서 pull하고 재시작한다. 사람이 하는 일이라 테스트를 건너뛰고, 태그를 헷갈리고, 배포 순서를 빠뜨린다. 그러다 금요일 저녁에 사고가 난다.

CI/CD의 핵심은 "사람이 매번 반복하던 일을 코드로 못 박아 자동으로 돌린다"는 것이다. 빌드·테스트·배포가 코드가 되면, 빠뜨릴 수도 헷갈릴 수도 없다.

GitHub Actions는 이 자동화를 GitHub 저장소 안에서 바로 해주는 도구다. 별도 서버를 세울 필요 없이, 저장소에 .yml 파일 하나를 두면 push·PR 같은 이벤트에 맞춰 워크플로가 실행된다. 이 글에서는 CI/CD가 무엇인지부터, 워크플로의 구조, 린트·테스트 자동화(CI), Docker 이미지 빌드·푸시, 그리고 배포(CD)까지 실제 .yml과 함께 단계별로 만든다.

---

1. CI/CD란 — 그리고 GitHub Actions

먼저 용어부터 정리하자.

• CI (Continuous Integration, 지속적 통합) — 코드를 자주 합치고, 합칠 때마다 자동으로 빌드·테스트해서 문제를 조기에 잡는 것. "이 변경이 뭔가 깨뜨리지 않았나?"를 매 push마다 기계가 검사한다.
• CD (Continuous Delivery/Deployment, 지속적 전달/배포) — CI를 통과한 결과물을 자동으로 배포 가능한 상태로 만들거나, 실제로 배포하는 것. 테스트를 통과한 바로 그 이미지를 그대로 내보낸다.

한 문장으로, CI는 "깨진 걸 일찍 잡는 그물", CD는 "검증된 걸 자동으로 내보내는 컨베이어"다.

GitHub Actions는 이 둘을 GitHub에 내장된 형태로 제공한다. 동작을 이해하려면 다섯 단어면 된다.

• Workflow — 자동화 전체. .github/workflows/ 안의 .yml 파일 하나가 워크플로 하나다.
• Event — 워크플로를 실행시키는 방아쇠. push, pull_request, 태그 생성 등.
• Job — 워크플로 안의 작업 단위. 여러 Job은 기본적으로 병렬 실행되며, 의존 관계를 줄 수 있다.
• Step — Job 안의 한 단계. 액션을 호출(uses)하거나 셸 명령을 실행(run)한다.
• Runner — Job을 실제로 실행하는 가상 머신(보통 ubuntu-latest). 매번 깨끗한 환경에서 시작한다.

---

2. 워크플로의 구조 — YAML 한 장 뜯어보기

워크플로 파일은 저장소의 .github/workflows/ 폴더에 둔다. 가장 작은 예제로 구조를 보자.

# .github/workflows/ci.yml
name: CI                       # 워크플로 이름 (Actions 탭에 표시)

on:                            # 언제 실행할지 — 이벤트
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:                        # job 이름
    runs-on: ubuntu-latest     # 어떤 runner에서 돌릴지
    steps:
      - uses: actions/checkout@v5      # 1) 저장소 코드 체크아웃
      - uses: actions/setup-node@v5    # 2) Node.js 설치
        with:
          node-version: "20"
          cache: "npm"                 # 의존성 캐시 (빌드 단축)
      - run: npm ci                    # 3) 의존성 설치
      - run: npm test                  # 4) 테스트 실행

읽는 법은 위에서 아래로 그대로다. on이 언제, jobs가 무엇을, steps가 어떤 순서로를 정의한다. uses는 남이 만든 재사용 액션을 가져다 쓰는 것이고(actions/checkout처럼), run은 셸 명령을 직접 실행하는 것이다.

이 파일을 저장소에 push하면, 그 순간부터 main에 대한 push와 PR마다 GitHub가 자동으로 이 워크플로를 돌린다. 저장소의 Actions 탭에서 실행 이력과 로그를 볼 수 있다.

버전 메모. 액션 버전(@v5, @v4 등)은 주기적으로 올라간다. 항상 메이저 태그로 핀하고(@main처럼 떠다니는 참조는 피한다), 실제 적용 시 GitHub Marketplace에서 최신 메이저 버전을 한 번 확인하는 게 좋다.

---

3. CI 파이프라인 — 린트·테스트 자동화

이제 실용적인 CI를 만들어보자. PR이 올라올 때마다 린트 → 테스트를 돌려서, 통과하지 못하면 머지를 막는 게 목표다.

# .github/workflows/ci.yml
name: CI

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

# 같은 브랜치에 새 push가 오면 진행 중이던 낡은 실행은 취소
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: ["20", "22"]      # 두 Node 버전에서 동시에 검증
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: ${{ matrix.node }}
          cache: "npm"
      - run: npm ci
      - run: npm run lint        # ESLint 등
      - run: npm test            # 테스트

몇 가지 실무 장치가 들어 있다.

• matrix — node: ["20", "22"]로 여러 버전에서 병렬로 같은 검증을 돌린다. 라이브러리나 다중 환경 지원에 유용하다.
• concurrency — 빠르게 연속 push할 때, 이미 돌고 있던 낡은 실행을 자동 취소해 낭비를 줄인다.
• cache: "npm" — 의존성을 캐시해 npm ci 시간을 크게 줄인다.

DB가 필요한 통합 테스트라면, services로 테스트용 컨테이너(예: PostgreSQL)를 띄울 수 있다. 여기서 Docker에서 배운 컨테이너 개념이 그대로 쓰인다.

    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_PASSWORD: testpass
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

push하면 Actions 탭에 결과가 뜬다. 통과하면 이런 모습이다.

✓ test (20)     1m 38s
✓ test (22)     1m 41s
All checks have passed

하나라도 실패하면 빨간 X가 뜨고, 브랜치 보호 규칙(뒤에서 설명)과 묶으면 그 PR은 머지가 막힌다. "테스트 통과 없이는 main에 못 들어온다"가 코드로 강제된다.

---

4. 이미지 빌드 & 푸시 — Docker와 연결

CI가 초록불이면, 이제 Docker 입문에서 만든 Dockerfile로 이미지를 빌드해 레지스트리에 올린다. 여기서는 GitHub가 무료로 제공하는 GitHub Container Registry(ghcr.io)에 푸시한다.

# .github/workflows/docker.yml
name: Build and Push Image

on:
  push:
    branches: [main]
    tags: ["v*.*.*"]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}   # 예: jinoism/myapp

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write              # ghcr.io 푸시에 필요
    steps:
      - uses: actions/checkout@v5

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Log in to GHCR
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}   # 자동 제공 — 별도 설정 불필요

      - name: Extract metadata (tags, labels)
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch          # 브랜치명 태그
            type=semver,pattern={{version}} # v1.2.3 태그
            type=sha,prefix=sha-            # 커밋 SHA 태그

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha           # GitHub Actions 캐시 활용
          cache-to: type=gha,mode=max

핵심 포인트만 짚자.

• permissions: packages: write — ghcr.io에 푸시하려면 이 권한이 필요하다.
• secrets.GITHUB_TOKEN — GitHub가 워크플로마다 자동 발급하는 토큰이라, GHCR 로그인에 별도 비밀키를 만들 필요가 없다.
• metadata-action — Git 정보(브랜치·태그·SHA)로 이미지 태그를 자동 생성한다. 손으로 태그를 붙이다 실수하는 일이 사라진다.
• cache-from/to: gha — 이전 빌드의 레이어 캐시를 재사용해 빌드를 단축한다(레이어 캐시 개념은 Docker 글 참고).

성공하면 저장소의 Packages에 이미지가 올라간다.

#9 exporting to image
#9 pushing ghcr.io/jinoism/myapp:main
#9 pushing ghcr.io/jinoism/myapp:sha-a1b2c3d
#9 DONE

이제 docker pull ghcr.io/jinoism/myapp:main으로 어디서든 같은 이미지를 받을 수 있다.

---

5. CD — 배포 자동화와 시크릿

마지막 조각이다. 빌드된 이미지를 실제 서버에 배포한다. 핵심은 "테스트를 통과한 바로 그 이미지를, 검증을 거쳐 내보낸다"는 흐름이다.

Job 사이 순서는 needs로 못 박는다. test가 통과해야 build가 돌고, build가 끝나야 deploy가 돈다.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      # ... (3번의 CI 내용)

  build:
    needs: test            # test 통과 후에만
    runs-on: ubuntu-latest
    steps:
      # ... (4번의 빌드·푸시 내용)

  deploy:
    needs: build           # build 성공 후에만
    runs-on: ubuntu-latest
    environment: production   # 승인 게이트 (아래 설명)
    steps:
      - name: Deploy over SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd /srv/myapp
            docker compose pull        # 새 이미지 받기
            docker compose up -d        # 무중단에 가깝게 교체

배포 단계의 핵심은 두 가지다.

시크릿(Secrets). 서버 주소·접속 키 같은 민감한 값은 절대 .yml에 하드코딩하지 않는다. 저장소 Settings → Secrets and variables → Actions에 등록하고, 워크플로에서는 ${{ secrets.이름 }}으로 참조한다. 코드에는 값이 드러나지 않고, 로그에도 마스킹된다.

승인 게이트(Environment). environment: production을 지정하고 그 환경에 필수 리뷰어를 걸어두면, 운영 배포 직전에 "Approve"를 눌러야 진행된다. 자동화하되 운영 배포만은 사람이 한 번 확인하는, 현실적인 절충이다.

위 예시는 SSH로 서버에 들어가 docker compose로 교체하는 단순한 방식이다. Vercel·AWS·Cloudflare 같은 플랫폼은 각자의 공식 액션이나 OIDC 연동을 제공하므로, 배포 대상에 맞는 액션으로 이 deploy Job만 갈아끼우면 된다.

---

6. 실전 팁 — 더 빠르고 안전하게

마지막으로, 굴려보면 곧 필요해지는 것들을 정리한다.

• 브랜치 보호 규칙 — Settings → Branches에서 main에 "상태 체크 통과 필수"를 걸면, CI가 초록불이 아닌 PR은 머지가 막힌다. CI를 "있으면 좋은 것"에서 "통과해야 하는 계약"으로 바꾼다.
• 캐시 — cache: "npm"(의존성)과 cache-from/to: gha(Docker 레이어)만 켜도 파이프라인 시간이 절반 이하로 줄곤 한다.
• concurrency — 연속 push 시 낡은 실행을 자동 취소해 runner 시간을 아낀다.
• 디버깅 — 실패한 Job의 로그를 펼쳐 보고, 전체가 아니라 "Re-run failed jobs"로 실패분만 다시 돌린다. 저장소 시크릿에 ACTIONS_STEP_DEBUG=true를 두면 더 자세한 로그가 나온다.
• 권한 최소화 — permissions는 필요한 것만 명시한다(예: 빌드 Job에만 packages: write). 기본을 좁히고 필요한 곳만 연다.

아래는 자주 쓰는 트리거를 정리한 표다.

트리거	언제 실행되나
push (branches)	특정 브랜치에 푸시할 때
pull_request	PR이 열리거나 갱신될 때
push (tags)	v1.2.3 같은 태그를 푸시할 때 (릴리스 배포에 적합)
workflow_dispatch	Actions 탭에서 수동 실행 버튼으로
schedule (cron)	정해진 시각마다 (야간 배치 등)

---

마치며

CI/CD는 "사람이 매번 반복하던 빌드·테스트·배포를 코드로 못 박아 자동화한다"는 발상이다. GitHub Actions는 이걸 저장소 안에서 .yml 한두 장으로 해결한다. push하면 테스트가 돌고(CI), 통과하면 같은 이미지를 빌드해 레지스트리에 올리고, 승인 후 배포되는(CD) 흐름이 한 번 갖춰지면, 배포는 더 이상 긴장되는 수작업이 아니라 일상이 된다.

핵심만 다시 짚으면, Event → Workflow → Job → Step 구조 위에서, needs로 순서를 잇고, 시크릿으로 민감 정보를 숨기고, 캐시로 속도를 올리고, 승인 게이트로 안전장치를 둔다. Docker에서 만든 이미지가 여기서 자동으로 빌드·배포되며 하나의 파이프라인으로 이어진다.

다음 단계는 컨테이너를 여러 서버에 걸쳐 운영하고 자동 복구·확장하는 오케스트레이션, 즉 Kubernetes다. 그건 별도 글에서 이어가겠다.

---

참고 출처

• GitHub Docs — Understanding GitHub Actions — https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions
• GitHub Docs — Publishing Docker images — https://docs.github.com/en/actions/publishing-packages/publishing-docker-images
• Docker Docs — Introduction to GitHub Actions — https://docs.docker.com/guides/gha/
• docker/build-push-action — https://github.com/docker/build-push-action
• docker/metadata-action — https://github.com/docker/metadata-action