# CI 러너 설정

`.github/workflows/ci.yml` 을 실제로 실행하는 Gitea Actions 러너 설정입니다.
**러너가 없으면 워크플로는 "Waiting for a runner" 상태로 대기만 합니다.**

## 어디에 띄울 것인가

| 위치 | 장점 | 단점 |
| --- | --- | --- |
| **Gitea 서버** (권장) | 항상 켜져 있어 CI 가 늘 동작 | 서버에 Docker 필요 |
| 개발 PC | 바로 시작 가능 | PC 가 꺼지면 CI 도 멈춤 |

CI 의 목적이 "내가 없어도 검사되는 것"이므로 서버 쪽을 권장합니다.

## 설치

```bash
# 1) 저장소 Settings → Actions → Runners → Create new Runner 에서 토큰 발급
# 2) 설정 파일 준비
cd ci
cp .env.example .env        # 편집기로 열어 GITEA_RUNNER_REGISTRATION_TOKEN 채우기

# 3) 기동
docker compose -f docker-compose.runner.yml --env-file .env up -d

# 4) 등록 확인
docker compose -f docker-compose.runner.yml --env-file .env logs -f runner
#    "Runner registered successfully" 가 보이면 성공
```

저장소 **Settings → Actions → Runners** 에서 러너가 **Idle** 로 표시되면 준비 완료입니다.
이후 푸시하면 Actions 탭에서 실행이 시작됩니다.

## 잘 안 될 때

| 증상 | 원인 | 해결 |
| --- | --- | --- |
| 잡이 계속 대기 중 | 라벨 불일치 | `RUNNER_LABELS` 의 `ubuntu-latest` 가 워크플로 `runs-on` 과 같은지 확인 |
| `uses:` 액션 다운로드 실패 | 서버에서 github.com 접근 불가 | 방화벽 확인. 폐쇄망이면 액션 미러 필요 |
| 등록 실패 (401/404) | 토큰 만료·오타, URL 끝 `/` | 토큰 재발급, `GITEA_INSTANCE_URL` 확인 |
| 잡 시작 직후 실패 | 도커 소켓 마운트 누락 | `/var/run/docker.sock` 마운트 확인 (Windows 는 `//var/run/docker.sock`) |
| **모든 스텝이 한꺼번에 실패**(checkout 포함) | 서비스 컨테이너가 뜨지 못함 | 아래 "서비스 컨테이너" 참고 |

## 서비스 컨테이너 주의 (GitHub Actions 와 다른 점)

Gitea 러너는 잡을 **컨테이너로** 실행하고 서비스와 같은 네트워크에 붙인다.
GitHub Actions 는 잡이 VM 위에서 직접 돌기 때문에 관례가 다르다.

| | GitHub Actions | Gitea act_runner |
| --- | --- | --- |
| 서비스 접근 주소 | `localhost` + `ports` 매핑 | **서비스 이름** (`postgres:5432`) |
| `ports:` 필요 여부 | 필요 | **불필요 — 오히려 해롭다** |

`ports: - 5432:5432` 를 두면 호스트 포트를 점유하려 하는데,
개발 DB 가 이미 그 포트를 쓰고 있으면 **잡이 시작조차 못 하고 모든 스텝이 failure 로 표시된다.**
(스텝이 실패한 게 아니라 잡 준비 단계에서 죽은 것이다)

`ci.yml` 의 backend 잡은 이 규칙에 맞춰 `ports` 없이 `DB_HOST: postgres` 를 쓴다.

## 리소스 참고

워크플로는 두 개로 나뉘어 있습니다.

**`ci.yml`** — 모든 푸시·PR 에서 실행

- `backend` — postgres 서비스 컨테이너를 띄워 단위 테스트와 e2e 를 실행
- `frontend` — lint·type-check·테스트
- `error-codes-sync` — 에러 코드 생성 파일 드리프트 검사

**`ci-flutter.yml`** — **기본적으로 돌지 않는다**

Flutter 는 SDK 다운로드로 매 실행 수 분이 걸리는데, backend/frontend 만 고친 커밋에서는
검사할 것이 없다. 그래서 다음 경우에만 실행된다.

- `flutter/` 아래 파일이 바뀐 푸시·PR — **실제로 Flutter 를 쓰기 시작하면 자동으로 동작한다**
- Actions 탭의 **Run workflow** 버튼으로 수동 실행

모바일 앱을 쓰지 않는 프로젝트라면 `ci-flutter.yml` 을 지우면 된다.

> 러너는 기본적으로 잡을 **하나씩** 처리한다. 전체 시간을 줄이려면 러너를 여러 개 띄우거나
> `act_runner` 설정에서 동시 실행 수를 늘린다.

## 주의

- **토큰은 `ci/.env` 에만** 둡니다. 이 파일은 루트 `.gitignore` 로 커밋되지 않습니다.
- `runner-data/` 에 등록 정보가 저장됩니다. 지우면 토큰으로 재등록해야 합니다.
- 러너는 도커 소켓에 접근하므로 **호스트에 대한 사실상의 관리자 권한**을 갖습니다.
  신뢰할 수 있는 저장소의 워크플로만 실행되도록 하세요 (공개 저장소의 PR 실행 정책 확인).