From 656e21ad9e877bc6e403c949c6710250babfb87f Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Mon, 14 Jul 2025 17:57:50 +0900
Subject: [PATCH] Add Gitea Actions self-hosted runner troubleshooting guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Document runner setup and configuration process
- Cover nginx config validation fixes
- Include permission and label matching issues
- Provide monitoring and debugging commands

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../20250714_gitea_actions_setup.md           | 197 ++++++++++++++++++
 1 file changed, 197 insertions(+)
 create mode 100644 docs/troubleshooting/20250714_gitea_actions_setup.md

diff --git a/docs/troubleshooting/20250714_gitea_actions_setup.md b/docs/troubleshooting/20250714_gitea_actions_setup.md
new file mode 100644
index 0000000..3ce4198
--- /dev/null
+++ b/docs/troubleshooting/20250714_gitea_actions_setup.md
@@ -0,0 +1,197 @@
+# 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 설치 확인
+
+```bash
+# 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 등록 (잘못된 라벨)
+
+**첫 번째 시도**:
+```bash
+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를 올바른 라벨로 재등록
+
+```bash
+# 기존 runner 종료
+killall act_runner
+
+# 설정 파일 삭제
+rm -f .runner
+
+# 대화형으로 재등록
+act_runner register
+# URL: http://localhost:3000
+# Token: j0JCOcmeK02Khp4uIROhj8enbACwqUVuhMjxn7FI
+# Name: admin-runner
+# Labels: self-hosted  # 중요!
+```
+
+### 5단계: Runner 실행
+
+```bash
+# /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로 검증 시도
+
+**해결책**: 임시 교체 방식으로 검증 방법 변경
+
+```yaml
+# 변경 전
+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
+```
+
+## 최종 구성
+
+### 워크플로우 설정
+```yaml
+jobs:
+  deploy:
+    runs-on: self-hosted  # Self-hosted runner 사용
+```
+
+### Runner 상태
+```bash
+# 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 권한
+```bash
+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. **모니터링 명령어**:
+   ```bash
+   # 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에 의해 자동 생성되었습니다.*
\ No newline at end of file