CI 러너 설정

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

어디에 띄울 것인가

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

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

설치

# 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 설정에서 동시 실행 수를 늘린다.

잡이 멈출 때

컨테이너 환경에서 잡이 간헐적으로 멈추는 경우가 있다 (CPU 0%, 네트워크 정지 상태로 진행 없음). 러너가 하나뿐이면 멈춘 잡 하나가 이후 모든 잡을 굶긴다.

그래서 모든 잡에 timeout-minutes 를 둔다. 상한에 걸리면 강제 종료되고 다음 잡으로 넘어간다. 새 잡을 추가할 때도 반드시 상한을 지정할 것.

멈춘 잡을 즉시 해제하려면 해당 컨테이너를 중지하면 된다 (러너가 실패로 처리하고 다음 잡을 집는다).

docker ps --format "{{.Names}}" | grep GITEA-ACTIONS   # 실행 중인 잡 컨테이너
docker stop <컨테이너명>

주의

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

4.9 KiB Raw Permalink Blame History