[Github-Actions] GitHub Self-Hosted Runner로 배포 문제 해결하기 (feat.SSH 포트 막힘?)

새로운 회사에서 GitHub Actions로 EC2 배포를 설정하려다 예상치 못한 벽에 부딪혔습니다. 22번 포트가 보안 정책으로 차단되어 있어 일반적인 GitHub 호스팅 러너로는 배포가 불가능했던 것입니다. 그래서 차라리 해당 EC2를 runner로 사용해서 배포하기로 했습니다. 처음엔 복잡해 보였지만 생각보다 훨씬 간단하게 해결할 수 있었습니다.

많은 개발자들이 self-hosted runner를 어렵게 생각하는데, 실제로는 몇 가지 핵심 포인트만 알면 쉽게 설정할 수 있습니다. 특히 서비스로 구성하는 부분을 놓치는 경우가 많은데, 이는 백그라운드 실행을 위해 반드시 필요한 단계입니다.

언제 Self-Hosted Runner가 필요한가?

일반적인 상황들:

• 특정 포트(SSH 22번 등)가 보안 정책으로 차단된 환경
• GitHub 호스팅 러너보다 더 많은 컴퓨팅 리소스가 필요한 경우
• 사내 네트워크 리소스에 접근해야 하는 배포 환경
• 특별한 소프트웨어나 설정이 미리 필요한 경우

GitHub의 호스팅 러너는 2-core CPU, 7GB RAM, 14GB SSD로 제한되어 있어, 더 강력한 하드웨어가 필요한 워크로드에는 부족할 수 있습니다.

 

GitHub의 일반 러너는 GitHub이 제공하는 서버(클라우드)에서 실행됩니다. 하지만 self-hosted runner는
내가 소유하거나 관리하는 서버에서 실행되어야 합니다. -> ex) EC2

핵심 설정 과정

1단계: GitHub에서 러너 등록 정보 가져오기

Repository → Settings → Actions → Runners → New self-hosted runner 클릭

여기서 중요한 것은 운영체제에 맞는 설정을 선택하는 것입니다. 저는 이번에 Linux를 선택했고 선택하면 아래와 같은 친절한 설명이 있습니다.  여기에 있는 명령어를 runner로 사용할 서버에 입력만 하면 됩니다!

2단계: EC2에서 러너 설치

3단계: 서비스로 구성하기 (필수!)

많은 사람들이 놓치는 핵심 단계입니다. 위 과정만 할시 터미널을 나오게 되면 종료되는데 러너를 서비스로 구성하면 머신이 시작될 때 자동으로 러너 애플리케이션이 시작됩니다.

 

https://docs.github.com/ko/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service

왜 서비스 구성이 중요한가?

• 서버 재부팅 시 자동으로 러너가 시작됨
• 백그라운드에서 지속적으로 실행됨
• ./run.sh 명령어로 수동 실행하면 터미널을 닫을 때 러너도 종료됨

4단계: 워크플로우에서 사용하기

.github/workflows/deploy.yml 파일에서:

name: Deploy to EC2

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: self-hosted  # 여기가 핵심!

네트워크 보안 고려사항

Self-hosted runner는 GitHub에서 작업을 받기 위해 443 포트(HTTPS)로의 아웃바운드 트래픽이 필요합니다. 인바운드 트래픽은 필요하지 않습니다.

보안 그룹 설정:

• 아웃바운드: 443 포트 허용 (GitHub와 통신용)
• 인바운드: 애플리케이션 요구사항에 따라 설정

자주 발생하는 문제와 해결책

문제 1: 러너가 오프라인 상태

원인: 서비스로 설정하지 않고 수동 실행했을 경우 해결: 위의 3단계 서비스 구성 단계 실행

문제 2: 토큰 에러

원인: 일회용 토큰이 만료됨 해결: GitHub에서 새로운 토큰 생성 후 재설정

문제 3: 권한 에러

원인: 서비스 파일의 사용자 권한 설정 문제 해결: sudo ./svc.sh install [USERNAME] 형태로 특정 사용자 지정

모니터링 및 확인

러너 상태 확인

# systemd 로그 확인
sudo journalctl -u actions.runner.* -f

# 서비스 상태 확인  
sudo ./svc.sh status

비용 효율성

Self-hosted runner는 GitHub Actions에서 무료로 사용할 수 있으며, 러너 머신 유지 비용만 부담하면 됩니다. 기존 EC2 인스턴스를 활용한다면 추가 비용 없이 더 나은 성능을 얻을 수 있습니다.

결론

SSH 포트 차단이라는 제약 상황에서 GitHub Self-Hosted Runner는 완벽한 해결책이었습니다. 핵심은 서비스로 구성하는 단계를 놓치지 않는 것입니다. 이 단계를 빼먹으면 러너가 지속적으로 동작하지 않아 배포가 실패할 수 있습니다.

처음에는 복잡해 보이지만, 한 번 설정하면 GitHub 호스팅 러너보다 더 안정적이고 강력한 배포 환경을 구축할 수 있습니다. 특히 보안 정책이 까다로운 기업 환경에서는 self-hosted runner가 거의 필수적인 선택이 될 수 있습니다.