Cloud & DevOps

GitHub Actions CI/CD 실전 가이드

한 줄 요약: GitHub Actions로 push 시 자동 테스트, PR 시 코드 리뷰, main 머지 시 배포까지 전체 CI/CD 파이프라인을 YAML 하나로 구성할 수 있다. GitHub Actions는 GitHub 저장소에 내장된 CI/CD 서비스로, 별도 서버 설정 없이 워크플로우를 정의할 수 있다. 코드가 이미 GitHub에 있다면 CI/CD도 GitHub에서 하는 게 가장 자연스럽습니다.

by Lee발행: 2026-04-08

한 줄 요약: GitHub Actions로 push 시 자동 테스트, PR 시 코드 리뷰, main 머지 시 배포까지 전체 CI/CD 파이프라인을 YAML 하나로 구성할 수 있다.

GitHub Actions는 GitHub 저장소에 내장된 CI/CD 서비스로, 별도 서버 설정 없이 워크플로우를 정의할 수 있다. 이 가이드는 실전에서 가장 많이 쓰는 패턴을 정리한다.

왜 GitHub Actions인가

코드가 이미 GitHub에 있다면 CI/CD도 GitHub에서 하는 게 가장 자연스럽습니다. 무료 2000분/월(퍼블릭 무제한), YAML 기반 설정, 마켓플레이스의 풍부한 액션.

워크플로우는 .github/workflows/ 디렉토리에 YAML 파일로 정의한다. 핵심 구조: trigger(on: push, pull_request), jobs(병렬 실행 가능한 작업 그룹), steps(순차 실행되는 개별 명령).

CI + 배포 워크플로우
name: CI/CD
on:
  push: { branches: [main] }
  pull_request: { branches: [main] }

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm run lint
      - run: npm test

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}

캐싱으로 CI 속도를 크게 단축할 수 있다. actions/cache로 node_modules를 캐싱하면 npm ci 시간이 수십 초에서 수 초로 줄어든다. 또는 actions/setup-node@v4의 cache: 'npm' 옵션으로 간편하게 설정 가능하다.

기본 워크플로우 구조

핵심 구조: on(트리거) → jobs(작업 단위) → steps(단계). push/PR 시 자동 실행되며, 행렬 전략으로 여러 환경을 병렬 테스트할 수 있습니다.

실전 레시피

자주 쓰는 워크플로우: PR 시 린트+테스트, main 머지 시 자동 배포, 스케줄 기반 정기 작업, AI 코드 리뷰 연동(Claude Code).

고급 워크플로우 패턴

Matrix 빌드: Node.js 18/20/22, OS Linux/macOS/Windows 조합으로 여러 환경에서 동시에 테스트. Reusable Workflows: 공통 CI 로직을 별도 저장소에 정의하고 다른 프로젝트에서 호출. Path filtering: 특정 디렉토리가 변경될 때만 해당 서비스의 CI를 실행.

비용 팁: 퍼블릭 저장소는 GitHub Actions가 무료다. 프라이빗 저장소는 월 2,000분(무료 플랜) 기준으로, 캐싱과 path filtering으로 불필요한 실행을 줄여 분 사용량을 최적화하라.

1인 개발자 관점에서 이 주제가 왜 중요한가

이 글의 주제(GitHub Actions CI/CD 실전 가이드)를 다룰 때 저는 버셀 + 깃허브 액션으로 자동 배포를 운영하는 입장 관점에서 봅니다. 단순히 새 기능을 소개하는 입장이 아니라, 12개 한국어 사이트를 1인으로 운영하면서 매일 클로드 코드를 켜두고 작업하는 입장이라 의사결정의 기준이 다소 좁고 실용적인 편입니다. 신기술이 출시될 때마다 곧바로 도입하기보다는 우선 한두 사이트에 시범 도입해 두고, 운영 부담이 늘지 않는지 며칠 지켜본 뒤 전체 확산을 결정하는 식입니다.

가장 자주 보는 변수는 한국 결제 시 VAT 10% 환급 절차, 그리고 12개 사이트를 동시에 운영할 때 변수 분리 비용입니다. 두 변수는 신기술을 도입할지 말지 결정할 때 거의 매번 영향을 줍니다. 글의 본문은 위의 두 축을 직접 명시하지는 않지만, 본문에서 다루는 항목을 이 축에 비춰 보시면 본인 환경에 맞는지 빠르게 판단할 수 있습니다. 특히 1인 개발자의 현금흐름 한계 같은 운영 변수는 도구 자체 성능보다 더 큰 영향을 주는 경우가 많기 때문에 본문 비교표를 볼 때 같이 떠올리시면 좋습니다.

한 가지 더 강조하면, Cloud & DevOps 영역의 글을 읽을 때 저는 본문이 다루는 도구·서비스가 ① 한국 결제 가능 여부 ② 한국어 응답 품질 ③ 종량제 비용의 예측 가능성 ④ 1인 개발자 학습 시간 대비 효과, 네 항목을 모두 충족해야 실제 도입을 결정합니다. 네 항목 중 하나라도 명확하지 않으면 도입을 1~2주 미루는 편이고, 그 사이 같은 카테고리의 다른 글도 확인합니다.

본문의 각 비교·코드·체크리스트는 이 네 항목 중 어느 부분에 영향을 주는지 의식하면서 보시면 더 빠르게 결론에 도달하실 수 있습니다. 본 사이트의 다른 Cloud & DevOps 글과 함께 보시면 같은 평가 축이 반복되는 것을 확인하실 수 있습니다. 토픽 페이지 또는 같은 카테고리 태그를 따라가시면 동일한 평가 기준이 적용된 글을 한 번에 모아 보실 수 있습니다.

본인 환경에 적용하기 전 확인할 체크포인트

본문의 내용을 본인 환경에 적용하기 전에 다음 항목을 빠르게 확인하시면 도입 실패 가능성을 줄일 수 있습니다.

공식 문서 버전 일치 — 본문 작성 시점과 현재 배포 버전이 다른 경우, 같은 명령어가 다르게 동작할 수 있습니다.
한국 결제·환율 검증 — 카드 결제, 부가가치세 처리, 원화 환산 시점에 따라 실제 청구액이 본문 예시와 다를 수 있습니다.
기존 스택과의 호환성 — Next.js·Vercel·Supabase 같은 기본 스택과 충돌이 없는지 패키지 의존성을 먼저 확인하세요.
롤백 절차 사전 정리 — 도입 후 문제가 생겼을 때 1회 명령으로 이전 상태로 되돌릴 수 있는 절차를 도입 전에 메모해 두시면 운영 부담이 크게 줄어듭니다.

위 네 항목을 모두 통과하면 보통 1~2시간 내에 도입을 마칠 수 있고, 통과하지 못한 항목이 있다면 그 항목을 우선 해결한 뒤 다시 시작하는 것이 효율적입니다.

자주 묻는 질문

GitHub Actions CI/CD 실전 가이드, 한 줄로 정리하면 어떻게 되나요?

코드가 이미 깃허브에 있다면 .github/workflows/ 디렉토리에 YAML 파일 하나만 두면 push 시 자동 테스트, PR 시 린트, main 머지 시 자동 배포까지 한 곳에서 굴러갑니다. 핵심은 job을 test와 deploy로 나누고 deploy에 needs: test 와 if: github.ref로 main 한정을 거는 것, 그리고 actions/setup-node의 cache 옵션으로 npm 설치 시간을 줄여 무료 분을 아끼는 것입니다. 별도 CI 서버 없이 마켓플레이스 액션을 조합해 1인 운영에서도 배포 자동화를 거의 공짜로 끝낼 수 있다는 게 결론입니다.

실무에서 처음 도입할 때 가장 먼저 확인할 것은 무엇인가요?

처음 도입할 때 가장 먼저 정리할 것은 토큰과 시크릿입니다. 본문 배포 워크플로우의 secrets.VERCEL_TOKEN 처럼, 배포 키나 API 키를 워크플로우 파일에 직접 적지 말고 저장소 Settings의 Secrets에 등록한 뒤 참조해야 합니다. YAML에 평문으로 키를 박으면 그대로 깃허브에 커밋돼 노출됩니다. 그다음 확인할 것은 트리거 범위입니다. on: push 만 두면 모든 브랜치 푸시마다 워크플로우가 돌아 무료 분을 빠르게 소진하니, branches: [main] 처럼 대상을 좁히고 PR에는 테스트만, main 머지에만 배포가 돌도록 job을 나누는 게 좋습니다. 이 두 가지를 먼저 잡으면 actions/setup-node의 cache 옵션으로 속도를 올리는 일은 그다음에 천천히 하셔도 됩니다.

가장 자주 발생하는 실수나 함정은 무엇인가요?

가장 흔한 실수는 캐싱 없이 매 실행마다 npm ci 를 처음부터 돌려 CI가 느려지고 무료 분을 낭비하는 것입니다. actions/setup-node@v4 의 cache: npm 옵션 한 줄이면 설치 시간이 수십 초에서 수 초로 줄어듭니다. 두 번째 함정은 needs 의존성을 빼먹어 테스트가 끝나기도 전에 deploy job이 병렬로 실행되는 것입니다. deploy 에 needs: test 를 걸어야 테스트 통과 후에만 배포됩니다. 세 번째는 모든 푸시와 PR에 무거운 워크플로우를 다 돌리는 것인데, path filtering으로 실제 변경된 디렉토리에만 해당 CI가 돌게 하면 프라이빗 저장소의 월 2,000분 한도를 훨씬 오래 쓸 수 있습니다. 시크릿을 로그에 echo로 찍는 실수도 자주 보이니 디버깅 출력에 키가 섞이지 않도록 주의하셔야 합니다.

다른 대안과 비교했을 때 어떤 상황에 적합한가요?

코드 호스팅을 이미 깃허브에서 하고 있다면 GitHub Actions가 거의 기본값입니다. 저장소 안에 워크플로우가 같이 버전 관리되고, 퍼블릭 저장소는 무료에 마켓플레이스 액션이 풍부해서 1인 개발자나 소규모 팀이 별도 CI 서버를 띄울 필요가 없습니다. 반대로 부적합한 경우도 분명합니다. 빌드가 무겁고 분 사용량이 큰 프라이빗 저장소는 월 2,000분 무료 한도를 금세 넘겨 self-hosted 러너나 CircleCI 같은 전용 CI가 비용·속도 면에서 유리할 수 있고, 코드가 깃랩이나 비트버킷에 있다면 각 플랫폼 내장 CI(GitLab CI 등)를 쓰는 편이 통합 면에서 낫습니다. 즉 깃허브 중심·중소 규모면 적합, 멀티 클라우드 빌드 팜이 필요한 대형 파이프라인이면 전용 도구를 검토하시면 됩니다.

더 깊게 공부하려면 어떤 자료를 보면 좋을까요?

가장 먼저 GitHub Actions 공식 문서(docs.github.com/actions)의 Workflow syntax 페이지를 보시면 on·jobs·steps·needs·matrix 같은 키 전체 레퍼런스를 한 번에 잡을 수 있습니다. 그다음 깊이를 더하려면 두 가지 키워드를 추천합니다. 하나는 Reusable Workflows와 Composite Action으로, 여러 저장소에 같은 CI 로직을 복붙하지 않고 재사용하는 방법입니다. 다른 하나는 OIDC 기반 클라우드 인증인데, 시크릿에 장기 토큰을 박아두는 대신 단기 토큰으로 AWS·버셀에 배포하는 방식이라 키 유출 위험을 크게 줄입니다. 마켓플레이스에서 actions/cache와 setup-node의 cache 옵션 문서도 함께 읽으면 CI 속도 최적화까지 자연스럽게 이어집니다.

github-actionsci-cd자동화배포워크플로우