DOCS/docs/troubleshooting/20250714_gitea_actions_setup.md

Gitea Actions 설정 및 Self-hosted Runner 구성 가이드

날짜: 2025-07-14
작업자: Claude (RO-BEING 시스템 관리)

개요

nginx-infra 저장소에서 Gitea Actions 자동 배포를 설정하는 과정에서 발생한 문제들과 해결 방법을 기록합니다.

문제 상황

초기 문제: Runner 실행 환경 불일치

증상: Gitea Actions 워크플로우가 대기 상태(waiting)에서 벗어나지 못함

원인:

• 워크플로우: runs-on: ubuntu-latest (컨테이너 환경)
• 실제 작업: 로컬 시스템 /etc/nginx 직접 접근 시도
• → 컨테이너에서는 호스트 시스템 파일에 접근 불가

해결 과정

1단계: Self-hosted Runner 설치 확인

# act_runner 설치 상태 확인
which act_runner
# /usr/local/bin/act_runner

act_runner --version
# act_runner version v0.2.6

결과: 이미 설치되어 있었음

2단계: Runner 등록 토큰 생성

Gitea 웹 인터페이스에서:

1. Site Administration → Actions → Runners
2. "Create new Runner" 클릭
3. 등록 토큰 생성: j0JCOcmeK02Khp4uIROhj8enbACwqUVuhMjxn7FI

3단계: Runner 등록 (잘못된 라벨)

첫 번째 시도:

act_runner register --no-interactive \
  --instance http://localhost:3000 \
  --token j0JCOcmeK02Khp4uIROhj8enbACwqUVuhMjxn7FI \
  --name admin-runner \
  --labels ubuntu-latest

문제: 워크플로우에서 self-hosted를 요구하는데 ubuntu-latest 라벨로 등록

4단계: 라벨 불일치 문제 해결

원인:

• 워크플로우: runs-on: self-hosted
• Runner 라벨: ubuntu-latest
• → 매칭되지 않아 작업 할당 안됨

해결책: Runner를 올바른 라벨로 재등록

# 기존 runner 종료
killall act_runner

# 설정 파일 삭제
rm -f .runner

# 대화형으로 재등록
act_runner register
# URL: http://localhost:3000
# Token: j0JCOcmeK02Khp4uIROhj8enbACwqUVuhMjxn7FI
# Name: admin-runner
# Labels: self-hosted  # 중요!

5단계: Runner 실행

# /etc/act_runner 디렉토리에서 실행
cd /etc/act_runner
nohup act_runner daemon --config .runner > ~/act_runner.log 2>&1 &

핵심: admin 계정으로 실행하여 sudo NOPASSWD 권한 활용

6단계: 워크플로우 nginx 설정 검증 오류 수정

문제: nginx 설정 검증 단계에서 오류 발생

nginx: [emerg] "server" directive is not allowed here in /tmp/nginx-test-config:21

원인: -c 옵션으로 site 설정 파일을 전체 nginx.conf로 검증 시도

해결책: 임시 교체 방식으로 검증 방법 변경

# 변경 전
sudo nginx -t -c /tmp/nginx-test-config

# 변경 후  
sudo cp /etc/nginx/sites-available/default /etc/nginx/sites-available/default.temp.backup
sudo cp server-nginx-default /etc/nginx/sites-available/default
sudo nginx -t || {
  sudo cp /etc/nginx/sites-available/default.temp.backup /etc/nginx/sites-available/default
  exit 1
}
sudo cp /etc/nginx/sites-available/default.temp.backup /etc/nginx/sites-available/default

최종 구성

워크플로우 설정

jobs:
  deploy:
    runs-on: self-hosted  # Self-hosted runner 사용

Runner 상태

# Runner 프로세스 확인
ps aux | grep act_runner
# admin     429705  0.1  0.0 1243692 18304 pts/4   Sl   17:52   0:00 act_runner daemon

# Nginx 서비스 상태
sudo systemctl status nginx
# Active: active (running)

# Nginx 설정 검증
sudo nginx -t
# nginx: configuration file /etc/nginx/nginx.conf test is successful

권한 설정 확인

admin 계정 sudo 권한

sudo -l
# (ALL) NOPASSWD: ALL
# (ALL) NOPASSWD: /usr/sbin/nginx, /bin/systemctl * nginx, /bin/cp * /etc/nginx/sites-available/default

결과: admin 계정이 패스워드 없이 nginx 관련 sudo 명령 실행 가능

트러블슈팅

일반적인 문제들

문제: Gitea Actions가 waiting 상태에서 멈춤 해결: Runner 라벨과 워크플로우 runs-on 설정 일치 확인

문제: nginx 설정 검증 실패 (server directive error) 해결: 전체 nginx.conf 컨텍스트에서 검증하도록 방법 변경

문제: sudo 권한 없음 오류 해결: admin 계정으로 runner 실행 및 NOPASSWD 설정 확인

문제: 파일 권한 오류 (Permission denied) 해결: 로그 파일을 홈 디렉토리(~/)에 저장

권장 설정

1. Runner 등록 시 주의사항:

   • 라벨을 self-hosted로 정확히 설정
   • admin 계정에서 등록 및 실행

2. 디렉토리 구조:

   • Runner 설정: /etc/act_runner/.runner
   • 로그 파일: ~/act_runner.log

3. 모니터링 명령어:

   # Runner 상태 확인
   ps aux | grep act_runner
   
   # 로그 실시간 확인
   tail -f ~/act_runner.log
   
   # nginx 상태 확인
   sudo systemctl status nginx
   sudo nginx -t
   

참고 자료

• Gitea Actions 문서: https://docs.gitea.io/en-us/actions/
• act_runner GitHub: https://github.com/nektos/act_runner
• Nginx 설정: /etc/nginx/sites-available/default
• 워크플로우 파일: .gitea/workflows/deploy.yml

---

이 문서는 Claude에 의해 자동 생성되었습니다.