GitHub Actions로 CI/CD 자동화하기

1. 배경 및 CI/CD의 중요성

안녕하세요, 권퓨터입니다! 2026년, 소프트웨어 개발 환경은 그 어느 때보다 빠르게 변화하고 있습니다. 이러한 변화의 중심에는 바로 CI/CD(Continuous Integration/Continuous Deployment, 또는 Continuous Delivery)가 있습니다. CI/CD는 개발자가 코드 변경 사항을 공유 리포지토리에 주기적으로 통합하고, 자동으로 빌드 및 테스트를 거쳐 배포하는 일련의 과정을 의미합니다.

과거에는 개발자가 코드를 작성한 후 수동으로 빌드하고, 테스트하고, 서버에 배포하는 과정이 일반적이었습니다. 이 과정은 시간이 오래 걸릴 뿐만 아니라, 사람의 실수로 인한 오류 발생 가능성이 높았고, 개발 주기를 지연시키는 주범이었습니다. 특히 여러 개발자가 동시에 작업하는 대규모 프로젝트에서는 코드 통합 과정에서 발생하는 충돌과 버그를 해결하는 데 많은 시간과 노력이 소요되었습니다.

하지만 CI/CD를 도입하면 이러한 문제점들을 효과적으로 해결할 수 있습니다. 개발자가 코드를 푸시할 때마다 자동으로 빌드, 테스트, 배포가 이루어지므로, 변경 사항이 프로덕션 환경에 반영되기까지의 시간이 획기적으로 단축됩니다. 이는 개발팀의 생산성을 극대화하고, 소프트웨어의 품질을 향상시키며, 고객에게 더 빠르고 안정적인 서비스를 제공하는 데 결정적인 역할을 합니다.

특히 GitHub Actions는 GitHub 리포지토리와 긴밀하게 통합되어 있어, 별도의 CI/CD 서버를 구축하고 관리할 필요 없이 손쉽게 자동화 파이프라인을 구축할 수 있다는 강력한 장점을 가지고 있습니다. YAML 기반의 간단한 설정으로 복잡한 워크플로우를 정의할 수 있으며, 방대한 마켓플레이스를 통해 다양한 작업을 자동화할 수 있습니다. 이번 포스트에서는 GitHub Actions를 활용하여 실제 CI/CD 파이프라인을 구축하는 방법을 단계별로 상세히 알아보겠습니다.

2. GitHub Actions 기본 개념 이해

본격적인 파이프라인 구축에 앞서, GitHub Actions의 핵심 구성 요소를 이해하는 것이 중요합니다. GitHub Actions는 다음의 요소들로 이루어져 있습니다.

2.1. 워크플로우 (Workflow)

워크플로우는 GitHub Actions의 가장 기본적인 단위이자 자동화 프로세스 전체를 정의하는 YAML 파일입니다. 이 파일은 .github/workflows 디렉토리 내에 저장되며, 특정 이벤트가 발생했을 때 실행될 일련의 작업(Job)들을 명시합니다. 예를 들어, 코드가 푸시되거나 Pull Request가 열렸을 때 워크플로우가 트리거될 수 있습니다.

2.2. 이벤트 (Event)

이벤트는 워크플로우를 실행시키는 특정 활동을 의미합니다. 가장 흔한 이벤트는 push (코드 푸시), pull_request (Pull Request 생성/업데이트), workflow_dispatch (수동 실행) 등이 있습니다. GitHub는 수십 가지의 다양한 이벤트를 지원하여 개발자가 원하는 시점에 워크플로우를 유연하게 실행할 수 있도록 합니다.

2.3. 작업 (Job)

워크플로우 내에서 실행되는 독립적인 단위입니다. 각 작업은 가상 머신(Runner)에서 실행되며, 여러 단계(Step)로 구성될 수 있습니다. 예를 들어, 빌드 작업, 테스트 작업, 배포 작업 등이 별도의 Job으로 정의될 수 있습니다. 작업 간에는 의존성을 설정하여 특정 작업이 완료된 후에 다른 작업이 실행되도록 할 수 있습니다.

2.4. 단계 (Step)

작업 내에서 순차적으로 실행되는 개별 명령 또는 액션입니다. 각 단계는 쉘 명령어를 실행하거나, 미리 정의된 GitHub Actions를 호출할 수 있습니다. 예를 들어, 코드 체크아웃, 의존성 설치, 테스트 실행 등이 하나의 Step이 됩니다.

2.5. 액션 (Action)

액션은 복잡한 작업을 쉽게 재사용할 수 있도록 패키징된 코드입니다. GitHub 마켓플레이스에는 수많은 공식 및 커뮤니티 액션이 등록되어 있으며, 이를 활용하여 `actions/checkout`(리포지토리 체크아웃), `actions/setup-node`(Node.js 환경 설정) 등 다양한 기능을 손쉽게 사용할 수 있습니다. 커스텀 액션을 직접 만들어 사용할 수도 있습니다.

2.6. 러너 (Runner)

러너는 워크플로우의 작업을 실행하는 서버입니다. GitHub에서 호스팅하는 Ubuntu, Windows, macOS 기반의 가상 머신을 사용할 수도 있고, 자체 호스팅 러너(Self-hosted runner)를 사용하여 특정 환경에서 작업을 실행할 수도 있습니다. GitHub 호스팅 러너는 일정량의 무료 사용 시간을 제공합니다.

3. CI/CD 파이프라인 설계 및 구성 요소

효율적인 CI/CD 파이프라인을 구축하기 위해서는 사전에 어떤 단계를 거쳐야 할지 명확하게 설계하는 것이 중요합니다. 일반적인 웹 애플리케이션 개발을 기준으로 CI/CD 파이프라인의 핵심 단계를 살펴보겠습니다.

3.1. CI (Continuous Integration) 단계

지속적인 통합은 개발자가 작성한 코드가 메인 브랜치에 통합되기 전에 자동으로 검증하는 과정입니다.

3.2. CD (Continuous Deployment/Delivery) 단계

지속적인 배포 또는 전달은 CI 단계를 통과한 코드를 실제 서비스 환경에 배포하는 과정입니다. Deployment는 모든 변경 사항을 자동으로 프로덕션에 배포하는 것을 의미하고, Delivery는 수동 승인 단계를 거쳐 배포하는 것을 의미합니다.

4. 실전! GitHub Actions 워크플로우 구축

이제 실제로 GitHub Actions 워크플로우 파일을 작성하며 CI/CD 파이프라인을 구축해볼 시간입니다. 여기서는 Node.js 기반의 웹 애플리케이션을 예시로 들어, CI(빌드 및 테스트)와 CD(AWS EC2 배포) 단계를 하나의 워크플로우로 통합하는 방법을 보여드리겠습니다.

4.1. 프로젝트 준비: Node.js 웹 애플리케이션

간단한 Node.js 프로젝트를 가정해봅시다. `package.json`에는 `build`와 `test` 스크립트가 정의되어 있습니다.

예시 `package.json`:

{
  "name": "my-node-app",
  "version": "1.0.0",
  "description": "A simple Node.js application",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "build": "echo "Building project..." && mkdir -p dist && cp index.js dist/",
    "test": "echo "Running tests..." && exit 0"
  },
  "dependencies": {
    "express": "^4.17.1"
  },
  "devDependencies": {
    "jest": "^27.0.6"
  }
}

4.2. GitHub Secrets 설정

배포를 위해 필요한 민감한 정보(AWS 자격 증명, SSH 키 등)는 GitHub Secrets에 저장하여 보안을 강화해야 합니다. 리포지토리 설정에서 `Settings > Secrets and variables > Actions`로 이동하여 다음 Secret들을 추가합니다.

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
EC2_SSH_PRIVATE_KEY (EC2에 접속할 SSH 프라이빗 키)
EC2_HOST (EC2 퍼블릭 IP 또는 도메인)
EC2_USER (EC2 사용자 이름, 예: `ubuntu`, `ec2-user`)

4.3. CI/CD 워크플로우 파일 작성 (`.github/workflows/main.yml`)

이제 `.github/workflows/main.yml` 파일을 생성하고 아래 내용을 작성합니다. 이 워크플로우는 `main` 브랜치에 코드가 푸시될 때마다 실행됩니다.

name: CI/CD Pipeline for Node.js App

on:
  push:
    branches:
      - main # main 브랜치에 푸시될 때 워크플로우 실행

env:
  NODE_VERSION: '18.x' # 사용할 Node.js 버전
  AWS_REGION: 'ap-northeast-2' # AWS 리전 설정
  S3_BUCKET_NAME: 'kwonputer-node-app-artifacts-2026' # S3 버킷 이름 (고유해야 함)
  DEPLOY_DIR: '/home/{{ secrets.EC2_USER }}/node-app' # EC2 배포 경로

jobs:
  build-and-test:
    name: Build and Test
    runs-on: ubuntu-latest # Ubuntu 최신 버전 러너 사용

    steps:
      - name: Checkout code
        uses: actions/checkout@v4 # 리포지토리 코드 체크아웃

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }} # env에 정의된 Node.js 버전 사용

      - name: Install dependencies
        run: npm install # 프로젝트 의존성 설치

      - name: Run tests
        run: npm test # 테스트 실행

      - name: Build project
        run: npm run build # 프로젝트 빌드

      - name: Archive production artifacts
        run: |
          tar -cvf node-app.tar dist package.json package-lock.json # 빌드된 파일들을 tar로 압축
          ls -lh
      
      - name: Upload artifact to S3
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ env.AWS_REGION }}
      - run: aws s3 cp node-app.tar s3://${{ env.S3_BUCKET_NAME }}/node-app.tar # S3에 아티팩트 업로드

  deploy:
    name: Deploy to EC2
    runs-on: ubuntu-latest
    needs: build-and-test # build-and-test 작업이 성공해야 deploy 작업 실행

    steps:
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Download artifact from S3
        run: aws s3 cp s3://${{ env.S3_BUCKET_NAME }}/node-app.tar node-app.tar # S3에서 아티팩트 다운로드
      
      - name: Set up SSH key
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.EC2_SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan -H ${{ secrets.EC2_HOST }} >> ~/.ssh/known_hosts # EC2 호스트 키 추가
        env:
          EC2_SSH_PRIVATE_KEY: ${{ secrets.EC2_SSH_PRIVATE_KEY }}

      - name: Deploy to EC2
        run: |
          ssh -i ~/.ssh/id_rsa ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }} "
            mkdir -p ${{ env.DEPLOY_DIR }}
            cd ${{ env.DEPLOY_DIR }}
            # 기존 파일 백업 또는 삭제
            rm -rf current_app
            mkdir current_app
          "
          scp -i ~/.ssh/id_rsa node-app.tar ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }}:${{ env.DEPLOY_DIR }}/current_app/node-app.tar
          ssh -i ~/.ssh/id_rsa ${{ secrets.EC2_USER }}@${{ secrets.EC2_HOST }} "
            cd ${{ env.DEPLOY_DIR }}/current_app
            tar -xvf node-app.tar
            rm node-app.tar
            npm install # EC2 서버에서 의존성 재설치 (production dependencies만)
            # PM2 또는 systemd를 사용하여 애플리케이션 재시작
            # 예: pm2 restart node-app 또는 sudo systemctl restart node-app
            echo "Deployment successful!"
          "

이 워크플로우는 두 가지 주요 작업으로 구성됩니다:

1. `build-and-test` (CI) 작업:

• `actions/checkout@v4` 액션을 사용하여 리포지토리 코드를 러너로 가져옵니다.
• `actions/setup-node@v4` 액션으로 Node.js 환경을 설정합니다.
• `npm install`, `npm test`, `npm run build` 명령어를 실행하여 의존성 설치, 테스트, 빌드를 수행합니다.
• 빌드된 결과물(아티팩트)을 `node-app.tar`로 압축하고, `aws-actions/configure-aws-credentials@v4` 액션을 통해 AWS 자격 증명을 설정한 후 S3 버킷에 업로드합니다.

2. `deploy` (CD) 작업:

• `needs: build-and-test`를 통해 `build-and-test` 작업이 성공해야만 이 작업이 실행되도록 합니다.
• S3에서 압축된 아티팩트를 다운로드합니다.
• GitHub Secrets에 저장된 SSH 프라이빗 키를 러너에 설정하여 EC2 서버에 접속할 준비를 합니다.
• `ssh` 및 `scp` 명령어를 사용하여 EC2 서버에 아티팩트를 전송하고, 압축을 해제한 후 `npm install`을 실행하여 프로덕션 의존성을 설치합니다. 마지막으로 애플리케이션을 재시작하는 명령을 실행합니다 (예시에서는 주석 처리되어 있으니 실제 환경에 맞게 PM2 또는 systemd 명령어를 추가해야 합니다).

4.4. 다른 CI/CD 도구와의 비교

GitHub Actions 외에도 Jenkins, GitLab CI 등 다양한 CI/CD 도구들이 있습니다. 각 도구의 특징을 비교하여 프로젝트에 가장 적합한 도구를 선택하는 데 도움을 드리고자 합니다.

GitHub Actions는 GitHub을 주력으로 사용하는 팀에게 가장 유리하며, 간편한 설정과 풍부한 마켓플레이스를 통해 빠른 CI/CD 구축이 가능합니다. Jenkins는 가장 오래되고 유연하며 강력한 기능을 제공하지만, 직접 관리해야 하는 부담이 있습니다. GitLab CI는 GitLab 사용자에게 GitHub Actions와 유사한 통합된 경험을 제공합니다.

프로젝트의 규모, 팀의 숙련도, 사용 중인 VCS(버전 관리 시스템) 등에 따라 적합한 도구를 선택하는 것이 중요합니다. 하지만 2026년 현재, GitHub을 사용하고 있다면 GitHub Actions는 가장 접근성이 높고 효율적인 선택 중 하나입니다.

5. 일반적인 문제 해결 및 최적화 팁

CI/CD 파이프라인을 구축하다 보면 예상치 못한 문제에 부딪히거나, 성능을 개선하고 싶은 경우가 많습니다. 몇 가지 일반적인 문제와 그 해결책, 그리고 최적화 팁을 공유합니다.

5.1. 의존성 캐싱 (Caching Dependencies)

- name: Cache Node.js modules
  uses: actions/cache@v4
  with:
    path: ~/.npm # 캐시할 경로 (npm의 경우)
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} # 캐시 키
    restore-keys: |
      ${{ runner.os }}-node- # 캐시 미스 시 폴백 키

- name: Install dependencies
  run: npm install # 캐시된 의존성이 없으면 새로 설치

5.2. 환경 변수 보안 (Secure Environment Variables)

앞서 언급했듯이, API 키, 데이터베이스 비밀번호, 클라우드 자격 증명 등 민감한 정보는 절대 워크플로우 파일에 직접 노출해서는 안 됩니다. GitHub Secrets를 적극적으로 활용하세요. Secrets는 워크플로우 실행 시에만 환경 변수로 주입되며, 로그에도 표시되지 않습니다.

5.3. 워크플로우 디버깅 (Debugging Workflows)

워크플로우가 실패하면 GitHub Actions UI에서 해당 작업의 로그를 상세히 확인해야 합니다. 각 단계별로 출력되는 로그를 통해 어떤 명령어에서 오류가 발생했는지 파악할 수 있습니다.

로그 상세도 높이기: 특정 액션이나 명령어가 예상대로 작동하지 않을 경우, `ACTIONS_STEP_DEBUG` 환경 변수를 `true`로 설정하여 더 자세한 디버그 로그를 활성화할 수 있습니다. (리포지토리 Secrets에서 설정)

로컬에서 테스트: `act`와 같은 도구를 사용하면 GitHub Actions 워크플로우를 로컬 환경에서 실행하여 빠르게 디버깅할 수 있습니다. 이는 원격 러너에서 매번 실행하는 것보다 훨씬 효율적입니다.

5.4. 병렬 처리 및 매트릭스 전략

여러 버전의 Node.js, Python, 또는 다른 OS 환경에서 테스트를 실행해야 할 때가 있습니다. GitHub Actions의 `matrix` 전략을 사용하면 여러 조합에 대해 작업을 병렬로 실행할 수 있어 테스트 시간을 크게 단축하고 다양한 환경에서의 호환성을 보장할 수 있습니다.

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        node-version: [16.x, 18.x, 20.x] # 테스트할 Node.js 버전들
        os: [ubuntu-latest, windows-latest] # 테스트할 운영체제들

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js ${{ matrix.node-version }} on ${{ matrix.os }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm install
      - run: npm test

6. 자주 묻는 질문 (FAQ)

Q. GitHub Actions를 사용하면 어떤 장점이 있나요?

GitHub Actions는 GitHub 리포지토리와 완벽하게 통합되어 있어 별도의 CI/CD 서버 구축 및 관리 없이 자동화 파이프라인을 쉽게 구축할 수 있습니다. 또한, 방대한 마켓플레이스 액션으로 다양한 작업을 손쉽게 자동화할 수 있으며, 일정량의 무료 사용량을 제공하여 소규모 프로젝트나 개인 프로젝트에 매우 유용합니다.

Q. CI/CD 파이프라인 구축 시 가장 중요한 고려사항은 무엇인가요?

가장 중요한 고려사항은 보안과 안정성입니다. 민감한 정보는 GitHub Secrets에 안전하게 저장하고, 배포 실패 시 빠르게 롤백할 수 있는 전략을 마련해야 합니다. 또한, 파이프라인의 각 단계에서 충분한 테스트와 검증이 이루어지도록 설계하여 서비스의 품질을 유지하는 것이 중요합니다.

Q. GitHub Actions는 무료인가요?

네, GitHub Actions는 공개(Public) 리포지토리의 경우 무제한 무료 사용이 가능합니다. 개인(Private) 리포지토리의 경우 매월 일정량의 무료 사용 시간(예: 2,000분/월)을 제공하며, 이를 초과하면 사용량에 따라 비용이 청구됩니다. 대부분의 소규모 프로젝트에는 충분한 무료 사용량이 제공됩니다.

Q. CI/CD를 처음 도입하는 개발팀에 권퓨터님이 해줄 조언이 있다면?

처음부터 완벽한 파이프라인을 구축하려 하기보다는, 작게 시작하여 점진적으로 확장하는 것을 추천합니다. 먼저 코드 빌드 및 테스트 자동화(CI)부터 시작하고, 그 다음 단계적으로 스테이징 배포, 프로덕션 배포까지 자동화 범위를 넓혀가세요. 팀원들과 지속적으로 소통하며 피드백을 반영하고, 파이프라인을 개선해 나가는 것이 중요합니다.

7. 마무리: 개발 생산성의 미래

이번 포스트에서는 GitHub Actions를 활용하여 CI/CD 파이프라인을 구축하는 방법에 대해 상세히 알아보았습니다. 코드를 푸시하는 순간부터 빌드, 테스트, 그리고 배포까지 모든 과정이 자동으로 이루어지는 경험은 개발팀의 생산성을 비약적으로 향상시키고, 개발자가 본연의 업무인 코드 작성에 더욱 집중할 수 있도록 돕습니다.

2026년의 개발 환경은 더욱 빠르고 민첩한 대응을 요구하며, CI/CD는 이러한 요구사항을 충족시키기 위한 핵심적인 도구입니다. GitHub Actions는 그 중에서도 GitHub 생태계에 깊이 통합되어 있어, GitHub를 사용하는 모든 개발자에게 강력한 이점을 제공합니다. 초기 설정에 약간의 노력이 필요할 수 있지만, 한번 구축하고 나면 그 효율성은 상상 이상일 것입니다.

물론, 이 포스트에서 다룬 내용은 기본적인 파이프라인 구축에 불과합니다. 실제 프로덕션 환경에서는 롤백 전략, 모니터링 및 알림, 다중 환경 배포(개발/스테이징/프로덕션), 보안 강화 등 고려해야 할 요소들이 더 많습니다. 하지만 오늘 배운 기본기를 바탕으로 여러분의 프로젝트에 맞는 더욱 견고하고 효율적인 CI/CD 파이프라인을 구축해나가시길 바랍니다.

자동화된 개발 프로세스를 통해 여러분의 아이디어가 더 빠르고 안정적으로 사용자에게 전달될 수 있기를 권퓨터가 응원합니다! 궁금한 점이 있다면 언제든지 댓글로 남겨주세요.