GitHub Actions로 자동 배포하기

EC2에 Docker로 배포하기에서 손으로 한 배포를 자동화한다. 코드를 push하면 이미지가 만들어지고 서버에 반영되는 것까지 손을 대지 않는다.

#1. 무엇이 자동화되는가

EC2에 Docker로 배포하기에서는 배포할 때마다 이 순서를 손으로 밟는다.

사람이 하는 일은 git push 하나만 남는다.

자동화의 핵심 가치는 시간 절약이 아니다. 매번 똑같은 순서로 실행된다는 점이다. 손으로 하면 급할 때 한 단계를 빠뜨리고, 어제와 다른 태그를 붙이고, 누군가는 자기 노트북에서 빌드해 올린다. 그런 차이가 장애로 이어진다.

#2. 배포 스크립트를 서버에 두기

워크플로가 서버에서 실행할 명령을 스크립트로 만들어 둔다. 워크플로에 명령을 길게 늘어놓는 것보다 낫다 — 서버에서 직접 실행해 볼 수 있어서 문제가 생겼을 때 배포 과정 탓인지 스크립트 탓인지 가를 수 있다.

EC2에 접속해 만든다.

~/deploy.sh

#!/bin/bash
set -euo pipefail

TAG="${1:?이미지 태그를 인자로 넘겨야 한다}"
IMAGE="ghcr.io/<GitHub사용자명>/visit-counter:${TAG}"

echo "==> 이미지 내려받기: ${IMAGE}"
docker pull "${IMAGE}"

echo "==> 기존 컨테이너 정리"
docker rm -f visit-counter 2>/dev/null || true

echo "==> 새 컨테이너 실행"
docker run -d \
  --name visit-counter \
  -p 8080:8080 \
  --env-file "${HOME}/app.env" \
  --restart unless-stopped \
  "${IMAGE}"

echo "==> 배포 완료"
docker ps --filter name=visit-counter

chmod +x ~/deploy.sh

접속 정보 파일(~/app.env)은 EC2에 Docker로 배포하기에서 만든 것을 그대로 쓴다.

#3. 배포용 SSH 키 만들기

워크플로가 EC2에 접속하려면 개인 키가 필요하다. 인스턴스를 만들 때 받은 키를 그대로 쓰지 않는다.

그 키는 사람이 서버에 들어갈 때 쓰는 키다. GitHub에 넣는 순간 저장소 설정에 접근할 수 있는 사람이라면 누구든 서버에 들어올 수 있게 된다. 배포 전용 키를 따로 만들어 용도를 나눈다.

로컬에서 새 키를 만든다.

ssh-keygen -t ed25519 -f ~/.ssh/deploy_key -C "github-actions-deploy" -N ""

ssh-keygen -t ed25519 -f "$env:USERPROFILE\.ssh\deploy_key" -C github-actions-deploy -N '""'

공개 키를 EC2에 등록한다.

# 공개 키 내용을 확인해서
cat ~/.ssh/deploy_key.pub

# EC2에 접속한 뒤 authorized_keys 에 덧붙인다
echo "<복사한 공개 키 내용>" >> ~/.ssh/authorized_keys

cp ~/.ssh/authorized_keys ~/.ssh/authorized_keys.bak

등록이 끝나면 로컬에서 새 키로 접속되는지 먼저 확인한다. 워크플로를 돌리기 전에 여기서 검증해 두면 나중에 실패 원인을 좁히기 쉽다.

ssh -i ~/.ssh/deploy_key ec2-user@<EIP>

#4. 보안 그룹 — 여기서 한 번 막힌다

EC2 장에서 SSH(22)의 소스를 내 IP로 제한했다. 그런데 워크플로는 내 노트북이 아니라 GitHub이 빌려주는 가상 머신에서 돈다.

GitHub이 쓰는 IP 대역은 공개돼 있다.

curl -s https://api.github.com/meta | head -40

다만 actions 대역은 매우 넓고 수시로 바뀐다. 보안 그룹 규칙으로 넣어 관리하는 것은 현실적이지 않다.

실습에서는 22번을 열되 키 인증만 허용하는 선에서 타협한다. Amazon Linux 2023은 기본적으로 비밀번호 인증이 꺼져 있으므로, 키가 없으면 접속할 수 없다.

기존 SSH 규칙의 소스만 내 IP 에서 Anywhere-IPv4 로 바꾼다. 규칙을 새로 추가하는 것이 아니다.

SSH 22 의 소스를 0.0.0.0/0 으로 바꾼다

#5. Secrets 등록

저장소 → Settings → Secrets and variables → Actions → New repository secret

# EC2 에 접속한 상태에서 — ECDSA 키의 지문이다
ssh-keygen -lf /etc/ssh/ssh_host_ecdsa_key.pub
# 256 SHA256:AbCd...xyz root@ip-172-31-... (ECDSA)

ssh: handshake failed: ssh: host key fingerprint mismatch

New repository secret — 이름과 값을 넣는다

등록하고 나면 목록에는 이름만 남는다.

Settings → Secrets — 값은 보이지 않고 이름만 남는다

-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----

# 클립보드로 정확히 복사
cat ~/.ssh/deploy_key | clip        # Git Bash

# PowerShell 에서는 리다이렉션(<) 이 예약어라 쓸 수 없다
Get-Content "$env:USERPROFILE\.ssh\deploy_key" -Raw | Set-Clipboard

#6. 워크플로 작성

테스트를 하나 더하고, 저장소에 .github/workflows/deploy.yml 을 만든다.

#6-1. 테스트 먼저 — CI 의 C

워크플로가 빌드만 하면 "컴파일이 되는가"까지만 확인한다. 테스트가 통과해야 배포로 넘어가게 만들면 망가진 코드가 서버까지 가는 것을 한 단계 앞에서 막는다.

build.gradle 의 dependencies 에 테스트 라이브러리를 더하고, 맨 아래에 JUnit 설정을 둔다.

dependencies {
    // ... 기존 의존성 ...

    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
}

test { useJUnitPlatform() }

테스트는 데이터베이스 없이 도는 것으로 만든다. GitHub 의 러너에는 Supabase 접속 정보가 없고, 있어서도 안 된다(2절). 저장소(VisitCountRepository)를 가짜(mock)로 바꿔 끼우면 컨트롤러의 계산만 검사할 수 있다.

src/test/java/com/example/VisitCounterApplicationTest.java

package com.example;

import org.junit.jupiter.api.Test;

import java.util.List;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.Mockito.*;

// DB 없이 도는 단위 테스트 — 저장소(repo)를 가짜(mock)로 바꿔 끼운다
class VisitCounterApplicationTest {

    @Test
    void 기록이_없으면_현재_카운트는_0이다() {
        VisitCountRepository repo = mock(VisitCountRepository.class);
        when(repo.findAll()).thenReturn(List.of());

        assertEquals("현재 카운트: 0\n", new VisitCounterApplication(repo).count());
    }

    @Test
    void 방문하면_카운트가_1_오른다() {
        VisitCount saved = new VisitCount();
        saved.setCount(41);
        VisitCountRepository repo = mock(VisitCountRepository.class);
        when(repo.findAll()).thenReturn(List.of(saved));
        when(repo.save(any())).thenAnswer(inv -> inv.getArgument(0));

        assertEquals("방문 횟수: 42\n", new VisitCounterApplication(repo).visit());
    }
}

로컬에서 먼저 돌려 본다. 호스트에 JDK 가 없어도 Gradle 이미지로 된다.

docker run --rm -v "$PWD":/build -w /build gradle:8.14-jdk21 gradle test --no-daemon
# BUILD SUCCESSFUL

#6-2. 워크플로

name: deploy

on:
  push:
    branches: [main]

permissions:
  contents: read
  packages: write        # GHCR 에 올리려면 필요하다

# 배포는 한 번에 하나만 돈다. 앞 배포가 끝날 때까지 다음 실행은 기다린다.
concurrency:
  group: deploy
  cancel-in-progress: false

jobs:
  # ── CI: 테스트가 통과해야 다음 job 이 돈다 ───────────────────
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: '21'

      # Gradle 을 설치하고, 내려받은 의존성을 실행 사이에 캐시한다
      - uses: gradle/actions/setup-gradle@v6
        with:
          gradle-version: '8.14'

      - name: 테스트
        run: gradle test --no-daemon

  # ── CD: 이미지 빌드 → GHCR → EC2 배포 ───────────────────────
  build-and-deploy:
    needs: test
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v7

      # GHCR 은 이미지 이름이 전부 소문자여야 한다.
      # 사용자명에 대문자가 있으면 그대로 쓸 수 없어 여기서 변환한다.
      - name: 이미지 이름 결정
        run: echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY_OWNER,,}/visit-counter" >> $GITHUB_ENV

      - name: GHCR 로그인
        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}   # 따로 발급하지 않아도 된다

      # 빌드 캐시를 GitHub 에 저장하려면 buildx 빌더가 필요하다
      - uses: docker/setup-buildx-action@v4

      - name: 이미지 빌드 및 push
        uses: docker/build-push-action@v7
        with:
          context: .
          push: true
          tags: ${{ env.IMAGE }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: EC2 에 배포
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ec2-user
          key: ${{ secrets.EC2_SSH_KEY }}
          fingerprint: ${{ secrets.EC2_HOST_FINGERPRINT }}   # 진짜 내 서버인지 확인
          script: ~/deploy.sh ${{ github.sha }}

#짚어볼 점

job 이 둘이고, needs: test 가 순서를 정한다. test 가 실패하면 build-and-deploy 는 아예 시작하지 않는다. 이미지도 만들어지지 않고 서버도 건드리지 않는다. Actions 화면에서도 두 job 이 따로 표시되므로 테스트에서 막혔는지, 빌드·배포에서 막혔는지 바로 보인다.

빌드 캐시를 GitHub 에 둔다. 러너는 매번 새 가상 머신이라 그냥 두면 Gradle 의존성과 Docker 레이어를 처음부터 받는다. setup-gradle 은 Gradle 캐시를, cache-from/cache-to: type=gha 는 Docker 레이어 캐시를 실행 사이에 보관한다. type=gha 는 기본 Docker 빌더가 지원하지 않아 setup-buildx-action 이 필요하다. 이 교안에서 잰 값으로는 캐시가 없는 첫 build-and-deploy 가 2분 48초, 캐시가 채워진 다음 실행이 42초였다. 이때 이미지 빌드 단계는 전부 CACHED 였다.

secrets.GITHUB_TOKEN 은 만들지 않아도 있다. GitHub이 워크플로 실행마다 자동으로 발급하고 끝나면 폐기한다. 이것이 AWS ECR 대신 GHCR을 쓰는 실질적인 이유다. ECR로 올리려면 AWS 자격 증명을 따로 마련해야 한다.

태그를 latest 가 아니라 커밋 해시(github.sha)로 붙인다. latest 만 쓰면 지금 서버에서 도는 이미지가 어느 코드인지 알 수 없다. 해시를 붙이면 장애가 났을 때 이전 해시로 되돌리면 끝이다.

# 롤백 — 서버에서 이전 커밋의 「전체」 해시(40자)를 넘긴다
~/deploy.sh 3f2a1b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6

#7. 실행과 확인

코드를 수정하고 push한다.

git add .
git commit -m "test: 자동 배포 확인"
git push origin main

저장소의 Actions 탭에서 진행 상황을 볼 수 있다.

test 가 통과한 뒤에 build-and-deploy 가 돈다 — 선이 needs 다

보안 그룹을 아직 열지 않았다면 여기서 4절의 함정을 만난다. 빌드와 push 는 초록색으로 성공하고 마지막 단계에서만 실패한다.

빌드와 push 는 성공하고 SSH 단계에서만 실패한다

Drone SSH version 1.8.2
2026/09/17 23:14:03 dial tcp ***:22: i/o timeout
##[error]Process completed with exit code 1.

읽을 점이 두 가지 있다.

• i/o timeout — 거부(refused)가 아니라 무응답이다. 보안 그룹이 패킷을 조용히 버리면 이렇게 된다. 30초를 기다린 뒤 끝났다.

• *** — EIP 주소가 별표로 가려져 있다. EC2_HOST 가 Secret 이라 GitHub 이 로그에서 자동으로 지운 것이다. Secrets 가 로그에 새지 않는다는 말이 이렇게 확인된다.

보안 그룹 22번을 열고 Re-run jobs 를 누르면 통과한다.

각 단계를 펼치면 로그가 나온다. 실패하면 어느 단계에서 멈췄는지부터 본다. 빌드에서 멈췄는지, push에서 멈췄는지, SSH에서 멈췄는지에 따라 원인이 완전히 다르다.

성공하면 브라우저에서 확인한다.

http://<EIP>:8080

#8. 아직 남은 문제 — 배포 중 서비스가 끊긴다

배포는 자동화됐지만 deploy.sh 를 다시 보자.

docker rm -f visit-counter     # 서비스 중단 시작
docker run -d ...              # 새 컨테이너 기동

기존 컨테이너를 지우고 새로 띄운다. 그 사이에 들어온 요청은 전부 실패한다. Spring Boot가 기동을 마칠 때까지 수십 초가 걸리므로, 사용자에게는 그동안 서비스가 죽은 것으로 보인다.

배포 중에 확인해 보면 바로 드러난다.

while true; do curl -s -o /dev/null -w "%{http_code} " http://<EIP>:8080/; sleep 0.3; done

# Windows PowerShell — curl.exe 로 불러야 진짜 curl 이 실행된다
while ($true) { Write-Host -NoNewline "$(curl.exe -s -o NUL -w '%{http_code}' http://<EIP>:8080/) "; Start-Sleep -Milliseconds 300 }

루프를 돌려 둔 채로 git push 를 하고 화면을 지켜본다.

200 이 이어지다가 000 이 한동안 찍힌 뒤 다시 200 으로 돌아온다. 000 은 응답 코드를 하나도 받지 못했다는 뜻이다 — 8080 에서 듣는 프로세스가 없어 연결 자체가 거부된 것이다. (앞에 Nginx 가 있다면 Nginx 는 살아 있으므로 000 대신 502 가 찍힌다.)

Nginx로 무중단 배포하기에서 이 빈틈을 없앤다.

#9. 문제 해결

push 단계에서 denied: permission_denied 가 뜬다

permissions: packages: write 가 워크플로에 있는지 확인한다. 저장소 설정에서 Actions의 기본 권한이 읽기 전용으로 제한돼 있을 수도 있다 — Settings → Actions → General → Workflow permissions.

기본값은 Read repository contents and packages permissions — 읽기 전용이다

기본값이 읽기 전용이라는 점이 중요하다. 이 화면을 Read and write permissions 로 바꾸는 것보다, 워크플로에 permissions: 블록을 적어 필요한 권한만 주는 쪽이 낫다. 이 화면을 열어두면 저장소의 모든 워크플로가 쓰기 권한을 갖게 된다.

ssh: handshake failed: ssh: host key fingerprint mismatch

~/deploy.sh <커밋해시>
echo $?          # 0 이 아니면 실패
docker logs visit-counter

#10. 실습 정리

워크플로와 컨테이너는 그대로 둔다. Nginx로 무중단 배포하기에서 deploy.sh 를 무중단 방식으로 고쳐 쓴다.

다음 장 — Nginx로 무중단 배포하기