ttipo
ea46fe7817
CI 워크플로는 저장소에 있지만 실행 주체(러너)가 없어 동작하지 않는 상태였다. 러너가 없으면 워크플로는 "Waiting for a runner" 로 대기만 한다. - ci/docker-compose.runner.yml — act_runner 를 별도 스택으로 분리. 앱 스택은 개발할 때만 띄우지만 러너는 항상 켜져 있어야 하므로 생명주기가 다르다. - ci/.env.example — 등록 토큰은 ci/.env 에만 두며 커밋되지 않는다. - ci/README.md — 설치 절차, 증상별 문제 해결, 잡별 리소스 특성. - 라벨 기본값이 워크플로의 runs-on(ubuntu-latest)과 일치하는지 교차 확인했다. 불일치는 잡이 영원히 대기하는 가장 흔한 원인이다. 러너가 도커 소켓에 접근해 사실상 호스트 관리자 권한을 갖는다는 점도 문서에 명시했다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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) |
리소스 참고
ci.yml 은 네 개의 잡을 실행합니다.
backend— postgres 서비스 컨테이너를 띄워 단위 테스트와 e2e 를 실행frontend— lint·type-check·테스트flutter— 매 실행마다 Flutter SDK 를 내려받아 수 분 소요error-codes-sync— 에러 코드 생성 파일 드리프트 검사
서버 사양이 넉넉하지 않다면 처음에는 flutter 잡을 빼고 시작해도 됩니다.
나머지 세 개만으로도 대부분의 회귀는 걸립니다.
주의
- 토큰은
ci/.env에만 둡니다. 이 파일은 루트.gitignore로 커밋되지 않습니다. runner-data/에 등록 정보가 저장됩니다. 지우면 토큰으로 재등록해야 합니다.- 러너는 도커 소켓에 접근하므로 호스트에 대한 사실상의 관리자 권한을 갖습니다. 신뢰할 수 있는 저장소의 워크플로만 실행되도록 하세요 (공개 저장소의 PR 실행 정책 확인).