[cloud ‐ troubleshooting] GitHub Actions Runner 환경 오동작 트러블슈팅 보고서 - 100-hours-a-week/5-yeosa-wiki GitHub Wiki

1. 문서 개요

  • 작성일: 2025-06-25

  • 작성자: aaron.lee(이유성)/클라우드

  • 시스템 범위: GitHub Actions Self-hosted Runner (Dev/Prod 통합 구성)

  • 목적:

    GitHub Actions Self-hosted Runner가 레이블 미지정으로 인해 Dev/Prod 환경 간 무작위로 워크플로우를 실행하여 발생한 DB 접속 오류 문제를 분석하고, 재발 방지를 위한 구조적 개선 사항을 정리합니다.

2. 시스템 구성 및 현상 개요

2.1 인프라 구성

환경 VM 이름 IP 주소 역할
Dev dev-cloudsql-proxy 10.1.30.4 Dev DB Proxy + Self-hosted Runner
Prod prod-cloudsql-proxy 10.0.40.4 Prod DB Proxy + Self-hosted Runner
DB dev-ongi-db 10.0.30.3 Cloud SQL (MySQL)

2.2 발생 현상

  • Dev 브랜치에서 워크플로우 실행 시 Access denied for user ...@'10.0.40.4' 오류 간헐 발생
  • Flyway Migration Job이 예상과 달리 Dev가 아닌 Prod Runner에서 실행되어 발생

3. 문제 정의

항목 내용
문제 유형 Self-hosted Runner가 잘못된 환경에서 Job을 실행
주요 증상 Flyway Migration 중 MySQL 접근 오류 (IP 미허용)
발생 조건 runs-on에 환경 레이블 미지정 (self-hosted, Linux, X64만 지정)
재현 가능성 50% 이상 (Pool 내 2대가 랜덤 선택되므로 반복 발생 가능)

4. 분석 및 확인 절차

4.1 GitHub Actions 로그 확인

  • Flyway Job 실행 로그에 Access denied ...@'10.0.40.4' 식별
  • Job은 self-hosted로 실행되었으나 구체적인 호스트 식별 불가

4.2 Runner 레이블 구성 점검

cat ~/actions-runner/.runner
# 결과:
# "labels": ["self-hosted", "Linux", "X64"]
  • Dev/Prod 모두 동일한 기본 레이블만 등록됨 → 구분 불가

4.3 GitHub 매칭 규칙 확인

  • runs-on에 지정된 모든 레이블을 만족하는 Runner 중 임의 선택(random)
  • 현재 구성에서는 두 VM 모두 매칭됨 → 무작위 선택됨

5. 원인 분석

  • 원인: Runner 레이블에 dev, prod 등 환경 구분 태그 누락
  • 동일 Runner Pool 내 VM들이 서로 다른 네트워크 조건을 가짐에도 불구하고, 레이블 미지정으로 인해 워크플로우가 랜덤으로 실행됨
  • 결과적으로 Dev DB는 dev Runner(10.1.30.4)에서만 허용되어 있음에도, prod Runner(10.0.40.4)에서 Job이 실행되어 IP 기반 인증 실패

6. 해결 방안

6.1 [권장] 레이블 기반 환경 고정화

환경 추가 레이블 runs-on 지정
Dev dev runs-on: [self-hosted, Linux, X64, dev]
Prod prod runs-on: [self-hosted, Linux, X64, prod]

6.2 [대안] Proxy 127.0.0.1 바인드

  • cloud_sql_proxy를 127.0.0.1:3306에만 바인드
  • 모든 Runner에서 localhost로 접속 → MySQL 권한도 [email protected]로 통일
  • 단점: proxy 세부 구성과 Flyway URL 변경 필요

6.3 [비추천] MySQL 권한을 모든 호스트에 부여

GRANT ALL PRIVILEGES ON db.* TO 'user'@'10.0.40.4';
  • 보안상 위험 → VM 환경이 늘어날수록 통제 불가능

7. 해결 조치 및 검증 결과

항목 조치 내용
레이블 재지정 Dev: dev, Prod: prod 태그 지정 후 ./config.sh --labels 재등록
systemd 적용 svc.sh install && start로 자동 실행
워크플로우 수정 runs-on: [self-hosted, Linux, X64, dev] 명시
테스트 Dev 브랜치 PR → dev Runner에서만 실행 확인Prod 브랜치 PR → prod Runner에서만 실행 확인
  • 결과: 이후 모든 워크플로우에서 환경 오동작 없음

8. 결론 및 권고사항

결론

  • GitHub Self-hosted Runner는 레이블 기반으로 실행 대상을 결정하므로, 명확한 환경 식별 레이블 없이 구성하면 실행 환경이 불안정해짐
  • 환경 간 네트워크, DB 권한, 파일 경로 등이 상이한 경우에는 Runner를 명확히 구분하는 레이블을 필수로 구성해야 함

권고사항

항목 권고 내용
Runner 레이블 관리 self-hosted, OS, 아키텍처 외에 환경 구분 레이블(dev/prod) 필수
워크플로우 작성 runs-on 항목에 환경 태그 포함 (예: dev, prod)
Runner Pool 관리 불필요한 레이블 중복 제거 및 환경별 Runner 분리 배포
보안 정책 DB 사용자 권한은 최소화하고, Runner IP 또는 호스트명을 기반으로 관리
모니터링 journalctl, GitHub Actions UI 등으로 Runner 실행 히스토리 주기 확인