해당 글에서는 Self-hosted Runner기반으로 Docker Compose로 구성된 파일을 배포하는 사용 사례입니다.
1) GitHub Actions Runner
💡 GitHub Actions Runner - GitHub Actions 워크플로우를 실제로 실행하는 에이전트(프로세스)입니다. - GitHub 리포지토리에 정의된 .github/workflows/*.yml 파일의 작업(Job)을 받아서, 해당 명령어들을 순차적으로 수행하는 역할을 합니다.
항목
Github-hosted Runner
Self-hosted Runner
실행 주체
GitHub 클라우드 서버
내 서버
설정 난이도
쉬움 (바로 사용)
높음 (Runner 설치 필요)
비용
무료 한도 후 과금
서버 비용만
내부망 접근
불가
가능
실행 환경
매 Job마다 초기화
환경 유지
캐시 유지
불가 (actions/cache 필요)
가능
보안 관리
GitHub이 관리
직접 관리
OS 선택
ubuntu / windows / macos
자유롭게 설정
실행 시간 제한
6시간/Job
제한 없음
적합한 상황
오픈소스, 외부 배포
사내 서버 배포, 내부망 연동
1. GitHub-hosted Runner
💡 GitHub-hosted Runner - GitHub가 제공하는 클라우드 서버에서 Actions Job을 실행하는 방식을 의미하며, 별도 서버 설정 없이 바로 사용 가능합니다. - Self-Hosted와 가장 큰 차이점은 실행 주체가 ‘Github 서버’가 됩니다
[처리 과정]
1. 이벤트 발생
- Actions를 시작시키는 출발점으로 개발자가 코드를 push하거나 PR을 열거나, 설정한 스케줄 시간이 되면 GitHub이 이벤트를 감지합니다.
2. GitHub Actions 트리거
- .github/workflows/*.yml 파일을 읽어서 어떤 Job을 실행할지 파악하며, on: push 같은 트리거 조건이 일치하면 워크플로우가 시작됩니다
3. GitHub 클라우드 서버 할당
- runs-on: ubuntu-latest 설정을 보고 GitHub이 클라우드 서버를 새로 생성해서 할당합니다. - 이 서버는 Job 실행을 위해 완전히 새로운 환경으로 시작이 되며, Node, Java, Docker 등 기본 툴은 이미 설치되어 있습니다.
4. Job 실행 (빌드 → 테스트 → 배포)
- 워크플로우에 정의된 steps를 순서대로 실행하며, 각 step은 독립적으로 실행되고 이전 step이 실패하면 기본적으로 이후 step은 중단이 됩니다.
5. Runner 종료
- Job이 끝나면 할당됐던 클라우드 서버가 완전히 삭제가 됩니다. 다음 Job 실행 시 항상 새 서버에서 시작 — 이전 실행의 파일, 캐시, 환경변수 등이 전혀 남지 않습니다.
# Create a folder
$ mkdir actions-runner && cd actions-runnerCopied!
# Download the latest runner package
$ curl -o actions-runner-linux-arm64-2.334.0.tar.gz -L <https://github.com/actions/runner/releases/download/v2.334.0/actions-runner-linux-arm64-2.334.0.tar.gzCopied>!
# Optional: Validate the hash
$ echo "xxxxxxx actions-runner-linux-arm64-2.334.0.tar.gz" | shasum -a 256 -c
# Extract the installer
$ tar xzf ./actions-runner-linux-arm64-2.334.0.tar.gz
2. 추가 설정(Configure) 명령어를 입력합니다.
💡 추가 설정(Configure) 명령어를 입력합니다.
- 아래와 같이 실제 수행이 됨을 확인하였습니다.
# Create the runner and start the configuration experience
$ ./config.sh --url https://github.com/xxxxx/xxxxx --token xxxxx
# Last step, run it!
$ ./run.sh
3. 백그라운드에서 run.sh 파일 수행
💡 백그라운드에서 run.sh 파일 수행
- ./run.sh 파일을 수행하면 터미널에서 세션이 사라지게 되면, 리스너가 종료가 됩니다. 그렇기에 백그라운드로 수행하도록 수행합니다.
# 터미널 종료해도 백그라운드에서 계속 실행
$ nohup ./run.sh &
💡 [참고] 실행중인 러너와 확인 후 종료 방법
# 실행중인 러너를 확인
ps aux | grep Runner.Listener
# PID 확인 후 종료
kill [PID]
4) Action 구성 : Front-end
1. 루트 경로에 .github/workflows 폴더를 생성하고 deploy.yml 파일을 생성합니다.
2. deploy.yml 구성하기
💡 deploy.yml 구성하기
- 아래와 같은 구성을 수행하였습니다. - 해당 처리 과정은 release-xxx 브랜치로 'pull Request'가 발생하였을 때, 아래와 같은 Action이 수행이 됩니다.
단계
이름
설명
1
소스코드 체크아웃
레포 코드를 Runner 서버로 내려받음
2
Node.js 설정
Node.js 24 버전 설치
3
Yarn 활성화
corepack으로 Yarn 활성화
4
의존성 설치
yarn.lock 기준으로 패키지 설치
5
빌드
Vite production 빌드 → dist/ 생성
6
Docker 이미지 빌드
dist/를 포함한 Docker 이미지 생성
7
기존 컨테이너 중지 및 제거
실행 중인 컨테이너 종료/삭제
8
컨테이너 실행
compose로 새 이미지 컨테이너 재시작
9
오래된 이미지 정리
사용하지 않는 Docker 이미지 삭제
name: Deploy xxx
on:
push:
branches:
- release-xxx
jobs:
deploy:
runs-on: self-hosted
steps:
- name: 소스코드 체크아웃
uses: actions/checkout@v4
- name: Node.js 설정
uses: actions/setup-node@v4
with:
node-version: '24'
- name: Yarn 활성화
run: corepack enable
- name: 의존성 설치
run: yarn install --immutable
- name: 빌드
run: yarn build --mode production
- name: Docker 이미지 빌드
run: docker build --platform linux/amd64 -f Dockerfile -t xxx-xxx-web .
- name: 기존 컨테이너 중지 및 제거
run: |
docker stop xxx-web || true
docker rm xxx-web || true
- name: 컨테이너 실행
run: docker compose -f /home/tomcat/compose.yaml up -d web
- name: 오래된 이미지 정리
run: docker image prune -f
3. 실행 확인
💡 실행 확인
- 실행한 환경에 맞게 정상적으로 수행이 됨을 확인하였습니다.
5) Action 구성 : Back-end
1. 루트 경로에 .github/workflows 폴더를 생성하고 deploy.yml 파일을 생성합니다.
💡 [참고] 최초 배포를 하는 경우 아래와 같은 오류가 발생하였습니다.
- Git 내에 gradle-wrapper.jar가 올라가지 않은 상태이기에 이를 포함하여 올려줍니다.
git add -f gradle/wrapper/gradle-wrapper.jar
2. deploy.yml 구성하기
💡 deploy.yml 구성하기
- 아래와 같은 구성을 수행하였습니다. - 해당 처리 과정은 release-xxx로 pull Request가 발생하였을 때, 아래와 같은 Action이 수행이 됩니다.
단계
이름
설명
1
소스코드 체크아웃
레포 코드를 Runner 서버로 내려받음
2
Java 설정
Amazon Corretto 21 버전 설치
3
Gradle 빌드
bootJar로 실행 가능한 JAR 파일 생성
4
Docker 이미지 빌드
JAR를 포함한 Docker 이미지 생성
5
기존 컨테이너 중지 및 제거
실행 중인 컨테이너 종료/삭제
6
컨테이너 실행
compose로 새 이미지 컨테이너 재시작
7
오래된 이미지 정리
사용하지 않는 Docker 이미지 삭제
name: Deploy API
on:
push:
branches:
- release-xxx
jobs:
deploy:
runs-on: self-hosted
steps:
- name: 소스코드 체크아웃
uses: actions/checkout@v4
- name: Java 설정
uses: actions/setup-java@v4
with:
java-version: '21'
distribution: 'corretto'
- name: Gradle 빌드
run: ./gradlew bootJar
- name: Docker 이미지 빌드
run: docker build --platform linux/amd64 -f Dockerfile -t dkcns-homepage-api .
- name: 기존 컨테이너 중지 및 제거
run: |
docker stop xxx-api || true
docker rm xxx-api || true
- name: 컨테이너 실행
run: |
docker compose -f /home/tomcat/compose.yaml up -d api
- name: 오래된 이미지 정리
run: docker image prune -f
