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 설치 확인

```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
   ```

## 조직 레벨 Runner 설정 (추가)

### 개별 저장소 → 조직 공유 Runner 변경

**배경**: 각 저장소마다 개별 runner를 설정하는 것보다 조직 단위 공유 runner가 효율적

**절차**:

1. **기존 runner 정리**:
```bash
killall act_runner
rm -f .runner
rm -f /etc/act_runner/.runner
```

2. **조직 runner 토큰 생성**:
   - Gitea 웹 → Organizations → ivada_Ro-being → Settings → Actions → Runners
   - "Add new runner" 클릭
   - 조직 토큰 생성: `kn5nLcoJgHUh4vgdPTF2cjL9eOHPOArWIHGFJIQq`

3. **조직 레벨 runner 등록**:
```bash
cd /etc/act_runner
act_runner register
# URL: http://localhost:3000
# Token: kn5nLcoJgHUh4vgdPTF2cjL9eOHPOArWIHGFJIQq
# Name: org-shared-runner
# Labels: self-hosted
```

4. **실행**:
```bash
cd /etc/act_runner
nohup act_runner daemon --config .runner > ~/org_runner.log 2>&1 &
```

**장점**:
- ✅ 모든 조직 저장소에서 자동 사용 가능
- ✅ 통합 관리 및 모니터링
- ✅ Runner 리소스 효율적 활용
- ✅ 권한 설정 간편

**적용 저장소**:
- nginx-infra
- test (Python FastAPI)
- frontend-base
- api-base
- 기타 모든 ivada_Ro-being 저장소

### 트러블슈팅 (조직 Runner)

**문제**: `runner registration token not found`
**원인**: 토큰 만료 또는 잘못된 조직 설정
**해결**: 새 토큰 생성 또는 조직 Actions 설정 확인

**문제**: 조직 runner가 개별 저장소에서 인식 안됨
**해결**: 저장소 Actions 설정에서 "Allow organization runners" 활성화

## 참고 자료

- **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`
- **조직 Runner 로그**: `~/org_runner.log`

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