arasystem/ci/README.md

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 <컨테이너명>

주의

• 같은 PC 에 다른 프로젝트의 러너가 있으면 RUNNER_NAME 을 겹치지 않게 짓습니다. compose 의 프로젝트 이름이 이 값이고(docker-compose.runner.yml 의 name:), 컨테이너 이름도 이 값입니다. 프로젝트 이름을 비워 두면 폴더 이름 ci 가 되어, 같은 템플릿을 쓰는 다른 프로젝트의 러너(역시 ci · 서비스 runner)와 겹치고 up 이 그쪽 컨테이너를 지운 뒤 이 러너로 다시 만듭니다 (2026-10-28 에 겪을 뻔했다 — 띄우기 전에 docker compose ls -a 로 이름을 본다).
• 러너 이미지는 판까지 고정합니다(gitea/act_runner:0.6.1) — 올릴 때는 docker 스킬의 "이미지 버전 고정" 갱신 규칙을 따릅니다.
• 토큰은 ci/.env 에만 둡니다. 이 파일은 루트 .gitignore 로 커밋되지 않습니다.
• runner-data/ 에 등록 정보가 저장됩니다. 지우면 토큰으로 재등록해야 합니다.
• 러너는 도커 소켓에 접근하므로 호스트에 대한 사실상의 관리자 권한을 갖습니다. 신뢰할 수 있는 저장소의 워크플로만 실행되도록 하세요 (공개 저장소의 PR 실행 정책 확인).