[ AWS ] GitHub Actions로 CI/CD 파이프라인 구축하기

[ AWS ] GitHub Actions로 CI/CD 파이프라인 구축하기

2026. 4. 1. 04:53ㆍ카테고리 없음

저번 포스팅에서는 Spring Boot 애플리케이션을 Docker 이미지로 빌드하고, AWS ECR에 업로드한 뒤 EC2 서버에서 Docker Compose로 실행하는 과정을 진행했습니다.

그런데 문제가 하나 있었죠? 코드를 수정할 때마다 아래의 긴 과정을 매번 반복해야 했습니다.

1. 로컬에서 Gradle 빌드

2. Docker 이미지 빌드

3. ECR에 push

4. EC2에서 pull 후 컨테이너 재실행

이번 포스팅에서는 이런 과정을 자동화해줄 CI/CD 파이프라인을 만들어보고,

GitHub Actions을 이용하여 GitHub에 코드를 push하는 것만으로 빌드부터 배포까지 자동으로 진행되는 시스템을 구축해보겠습니다.

CI/CD 란?

CI (Continuous Integration, 지속적 통합)

CI는 개발자가 작성한 코드를 정기적으로 공유 저장소(GitHub 등)에 통합하고, push된 코드가 배포가능한 상태인지가 자동으로 빌드 및 테스트하는 과정입니다.

저번에 로컬에서 ./gradlew build를 실행했던 이유는 도커 이미지를 만들기 위한 .jar 파일을 생성하기 위해서였습니다.

CI를 구축하면 이 과정을 수동으로 진행하지 않아도 GitHub Actions 서버가 이 빌드 과정을 대신 수행하게 됩니다.

CI 과정은 단순히 .jar파일만 만들어 줄 뿐 아니라, 코드를 합치는 과정에서 발생할 수 있는 컴파일 오류나 테스트 실패 여부를 즉시 확인해 주기 때문에, 배포가능한 상태인지 자동으로 검증할 수 있습니다.

정리해보면, CI란 작성한 코드가 서버에서 돌아갈 준비가 되었는지 검증하는 단계이며, 최종적으로 Jar 빌드 성공을 확인하는 과정이라고 할 수 있겠습니다.

CD (Continuous Deployment, 지속적 배포)

CD는 CI를 통해 검증된 빌드 결과물을 실제 운영 환경(AWS EC2 등)에 자동으로 반영하는 단계입니다.

CD 과정을 통해서 앞서 진행했던 docker 이미지 빌드, ECR push, 그리고 EC2에 접속해 docker pull 후 컨테이너를 재실행하는 일련의 과정들을 자동화합니다.

결과적으로, CI/CD를 구축해주면 github에 코드를 push하는 것만으로 자동 빌드/테스트 (CI) → 자동 배포 (CD) 까지의 전체 과정이 해결됩니다. 이렇게 전 과정을 자동화된 흐름으로 연결한 시스템을 파이프라인이라고 하는데요.

이번시간에는 Github Actions이라는 도구를 활용해 CI/CD 파이프라인을 설계해보겠습니다.

CI/CD 자동화 도구에는 대표적으로 Jekins와 Github Actions가 있습니다. 둘다 실무에서 정말 많이 쓰이는 도구인데요.

프로젝트나 실무 성격에 따라 골라서 사용되기 때문에 둘의 특성을 알고 계시면 좋을 것 같습니다.

GitHub Actions

스타트업이나 팀 프로젝트처럼 빠른 구축이 필요한 환경에서 주로 사용되며, 별도의 서버 구축 없이 바로 사용할 수 있는 점이 특징입니다.

GitHub 내부에서 CI를 실행하기 때문에 별도의 인프라가 필요하지 않고, GitHub에서 공식으로 제공하는 도구이기 때문에, GitHub 레포지토리를 기반으로 소스를 관리하는 프로젝트에서는 빠르게 CI/CD를 구축할 수 있다는 장점이 있습니다.

Jenkins
대기업이나 금융권, 공공기관처럼 보안 통제가 엄격한 내부망 환경에서 주로 사용되며, 커스터마이징 폭이 넓은 것이 특징입니다.
직접 내부 서버에 프로그램을 설치해서 운영하는 Self-hosted 구조이기 때문에, 네트워크 설정부터 보안 정책, 그리고 빌드가 돌아가는 러너 환경까지 하나하나 완전히 제어할 수 있습니다. 그래서 난이도가 높은 편이기도 합니다.

GitHub Actions 시작하기

저는 이번에 GitHub Actions를 사용해서 CI/CD를 구축해보겠습니다.

앞서 말씀드린 것처럼, GitHub Actions는 별다른 인프라나 설치가 필요없습니다.

오직 .github/workflows 라는 경로에 설정 파일 하나만 만들어주면 끝입니다. 같이 해보겠습니다.

Step 1. 워크플로우 설정 파일 생성하기

우리가 프로젝트 최상위 경로에 **.github/workflows**라는 폴더를 만들고 그 안에 .yml 파일을 넣어두면, GitHub은 코드가 Push 될 때마다 이 폴더를 제일 먼저 확인합니다.

워크플로우는 GitHub Actions에서 실행되는 자동화된 전체 프로세스를 의미합니다.

어떤 상황이 발생했을 때(Event), 어떤 순서로(Steps), 어떤 작업(Jobs)을 할 것인가? 를 정의해둔 시나리오라고 이해하시면 됩니다.

작성할 내용 3가지

1. 트리거 (Event)

2. 환경 설정 (Runner)

3. 작업 단계 (Steps)

작성할 위치

.github/workflows/ 디렉토리 안에 보통 deploy.yml(또는 .yaml)라는 이름으로 파일 생성

별도의 서버 없이 .github/workflows 디렉토리에 YAML 파일 하나만 작성하면, 특정 이벤트(push, PR 등)가 발생할 때 자동으로 지정한 작업을 실행해줍니다.

이번 포스팅에서 구축할 전체 흐름은 다음과 같습니다.

GitHub push → GitHub Actions 실행 → Gradle 빌드 → Docker 이미지 빌드 → ECR push → EC2 접속 → Docker Compose 재실행

1. workflow 파일 작성

프로젝트 루트 경로에 아래 디렉토리 구조로 workflow 파일을 생성해주세요.

.github/
└── workflows/
    └── deploy.yml

아래 내용을 deploy.yml 파일에 작성해주세요.

name: Deploy to EC2

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

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

      - name: JDK 17 설정
        uses: actions/setup-java@v3
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Gradle 빌드
        run: ./gradlew clean build -x test

      - name: AWS 자격증명 설정
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ap-northeast-2

      - name: ECR 로그인
        id: login-ecr
        uses: aws-actions/amazon-ecr-login@v1

      - name: Docker 이미지 빌드 및 ECR push
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: yesul-server
          IMAGE_TAG: latest
        run: |
          docker build --platform linux/amd64 -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

      - name: EC2 접속 후 배포
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ubuntu
          key: ${{ secrets.EC2_SSH_KEY }}
          script: |
            aws ecr get-login-password --region ap-northeast-2 | docker login --username AWS --password-stdin ${{ secrets.ECR_REGISTRY }}
            cd ~/yesul
            docker compose pull
            docker compose up -d
            docker image prune -f

각 step의 역할을 간단히 살펴보면 다음과 같습니다.

on.push.branches: main → main 브랜치에 push될 때 자동으로 실행됩니다.
actions/checkout → GitHub 저장소의 코드를 Actions 실행 환경으로 내려받습니다.
actions/setup-java → JDK 17 환경을 설정합니다.
Gradle 빌드 → -x test 옵션으로 테스트는 건너뛰고 jar 파일만 생성합니다.
configure-aws-credentials → GitHub Secrets에 저장된 IAM 키로 AWS 인증을 설정합니다.
amazon-ecr-login → ECR에 로그인합니다.
Docker 이미지 빌드 및 push → 이미지를 빌드하고 ECR에 업로드합니다.
appleboy/ssh-action → EC2에 SSH로 접속하여 최신 이미지를 pull받고 컨테이너를 재실행합니다.

2. GitHub Secrets 설정

workflow 파일에서 ${{ secrets.XXX }} 형태로 사용한 값들은 GitHub Secrets에 등록해야 합니다.

AWS 키나 SSH 키 같은 민감한 정보를 코드에 직접 작성하지 않고 안전하게 관리할 수 있는 방법입니다.

GitHub 저장소에서 [ Settings > Secrets and variables > Actions ] 로 이동한 뒤 [ New repository secret ] 을 눌러 아래 항목들을 하나씩 등록해주세요.

Secret 이름	값
AWS_ACCESS_KEY_ID	IAM 사용자 액세스 키 ID
AWS_SECRET_ACCESS_KEY	IAM 사용자 시크릿 액세스 키
ECR_REGISTRY	ECR 레지스트리 주소 (예: 123456789.dkr.ecr.ap-northeast-2.amazonaws.com)
EC2_HOST	EC2 퍼블릭 IP 주소
EC2_SSH_KEY	EC2 접속에 사용하는 .pem 키 파일의 전체 내용

💡 EC2_SSH_KEY 등록 방법

터미널에서 아래 명령어로 .pem 파일 내용을 출력한 뒤, 전체를 복사해서 Secret 값으로 등록하면 됩니다.

cat ~/.ssh/your-key.pem

-----BEGIN RSA PRIVATE KEY----- 부터 -----END RSA PRIVATE KEY----- 까지 전체를 복사해주세요.

3. EC2 사전 설정

GitHub Actions에서 EC2에 SSH로 접속한 뒤 AWS CLI 명령어를 실행하므로, EC2에도 몇 가지 사전 설정이 필요합니다.

IAM Role 연결 확인

이전 포스팅에서 ECR pull 권한을 가진 IAM Role을 EC2에 연결했습니다. 해당 Role이 잘 연결되어 있는지 확인해주세요.

(EC2 인스턴스 선택 > 작업 > 보안 > IAM 역할 수정 에서 확인 가능합니다.)

보안 그룹 SSH 포트 확인

GitHub Actions에서 EC2로 SSH 접속을 하기 때문에, EC2 보안 그룹의 인바운드 규칙에 22번 포트(SSH)가 허용되어 있어야 합니다.

보안을 위해 소스를 0.0.0.0/0 대신 GitHub Actions의 IP 대역으로 제한하는 것을 권장합니다만, 간단하게 진행하려면 0.0.0.0/0으로 설정해도 됩니다.

docker-compose.yml 파일 위치 확인

workflow의 배포 스크립트에서 cd ~/yesul 후 docker compose pull을 실행합니다.

EC2 서버의 ~/yesul 경로에 docker-compose.yml과 .env 파일이 있는지 확인해주세요. (이전 포스팅에서 생성한 경로입니다.)

4. 동작 확인

모든 설정이 완료되었다면, 이제 main 브랜치에 코드를 push해보겠습니다.

git add .
git commit -m "ci: add github actions workflow"
git push origin main

push 후 GitHub 저장소의 [ Actions ] 탭으로 이동하면 workflow가 실행되는 것을 확인할 수 있습니다.

각 step이 순서대로 실행되며, 모든 step에 초록색 체크가 표시되면 배포 성공입니다! 🎉

이후부터는 코드를 수정하고 main 브랜치에 push하기만 하면, 빌드부터 서버 배포까지 자동으로 처리됩니다.

EC2 인스턴스 생성부터 시작해서 Docker, ECR, Docker Compose, 그리고 CI/CD 파이프라인 구축까지 긴 여정이 마무리되었습니다.

처음엔 복잡해 보였지만, 하나씩 따라오다 보면 어느새 코드 push 한 번으로 자동 배포되는 환경이 완성되어 있을 겁니다. 수고 많으셨습니다! 😊

개발 지식 용량 늘리기