이 에러, 어떤 상황에서 만나나
어느 날 PR을 올리고 Actions 탭을 보는데 워크플로우가 계속 이 상태다.
Waiting for a runner to pick up this job...1분, 5분, 10분이 지나도 진행이 없다. 로그를 봐도 아무것도 없다. 그냥 저 메시지만.
처음엔 GitHub 서버 문제인가 싶어서 기다린다. 그러다 재실행 눌러보고, 안 되면 구글링을 시작한다. 이 글은 그 삽질을 줄이기 위한 정리다.
원인은 크게 세 가지
1. GitHub-hosted runner 공급 부족 (일시적)
GitHub에서 제공하는 ubuntu-latest, windows-latest 같은 공유 러너는 글로벌 수요를 함께 쓴다. 트래픽이 몰리는 시간대에는 진짜로 대기열에 걸린다. 특히 2026년 5월 GitHub Actions 장애처럼 플랫폼 자체 이슈일 때도 이 증상이 나온다.
확인 방법: GitHub Status 페이지 확인. Actions 항목에 이슈가 있으면 기다리는 게 답이다.
2. Self-hosted runner가 오프라인이거나 점유 중
Self-hosted runner를 직접 운영하는 경우, runner가 꺼져 있거나, 이미 다른 job을 처리 중이거나, 등록은 됐지만 실제로 연결이 끊긴 상태일 수 있다.
확인 방법: Repository → Settings → Actions → Runners. 상태가 Offline이거나 Idle인지 확인한다.
# runner 서비스 재시작 (Linux)
cd /path/to/actions-runner
./svc.sh stop
./svc.sh start
# 상태 확인
./svc.sh status3. Runner group 권한 문제
Organization에서 runner group을 사용하는 경우, 특정 repo가 해당 runner group에 접근 권한이 없으면 job이 영구적으로 대기 상태에 빠진다. 에러 메시지는 동일하게 "Waiting for a runner..."라서 원인을 찾기가 까다롭다.
확인 방법: Organization → Settings → Actions → Runner groups → 해당 그룹에서 "Repository access" 설정 확인.
상황별 체크리스트
| 상황 | 확인 포인트 | 조치 |
|---|---|---|
| GitHub-hosted runner 사용 중 | GitHub Status 페이지 | 장애면 대기, 아니면 재실행 |
| Self-hosted runner 사용 중 | Runner 온라인 상태 | runner 서비스 재시작 |
| Org runner group 사용 중 | Repository 접근 권한 | 그룹에 repo 추가 |
| runs-on 라벨 오타 | workflow yml의 runs-on 값 | 라벨 정확히 입력 |
| 동시 job 수 초과 | Concurrency 설정 | 제한 조정 또는 대기 |
| 특정 시간대만 발생 | GitHub 트래픽 패턴 | 재실행하거나 off-peak 배포 |
가장 흔한 실수 — runs-on 라벨 오타
Self-hosted runner에 라벨을 my-runner로 등록했는데 workflow에 my_runner라고 쓰는 경우다. 하이픈/언더바 혼용 실수가 생각보다 많다.
# 잘못된 예
jobs:
build:
runs-on: my_runner # 언더바 → 매칭 안 됨
# 올바른 예
jobs:
build:
runs-on: my-runner # 하이픈 → 등록된 라벨과 일치Runner에 등록된 라벨 목록은 Settings → Actions → Runners에서 확인 가능하다.
Self-hosted runner가 멈춰있을 때 — 완전 재등록
Runner 서비스가 좀비 상태로 남아있으면 재시작이 안 되는 경우도 있다. 이때는 제거 후 재등록이 깔끔하다.
# 1. 기존 runner 제거
cd /path/to/actions-runner
./config.sh remove --token YOUR_REMOVAL_TOKEN
# 2. 새로 등록 (GitHub → Settings → Actions → Runners → New self-hosted runner에서 토큰 발급)
./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_NEW_TOKEN
# 3. 서비스로 등록 및 시작
./svc.sh install
./svc.sh startActions Runner Controller (ARC) 사용 중이라면
Kubernetes 위에서 ARC(Actions Runner Controller)를 쓰는 경우, DesiredReplicas=0으로 고정되어 scale-up이 안 되는 버그가 있다. EphemeralRunner가 생성되지 않는 증상이 같이 나온다.
# ARC runner scale set 상태 확인
kubectl get autoscalingrunnerset -n YOUR_NAMESPACE
# ephemeralrunner 상태 확인
kubectl get ephemeralrunner -n YOUR_NAMESPACE
# controller 로그 확인
kubectl logs -n YOUR_NAMESPACE deployment/arc-controller-managerController 재시작으로 해소되는 경우가 많다.
kubectl rollout restart deployment/arc-controller-manager -n YOUR_NAMESPACEConcurrency 설정으로 인한 대기
workflow에 concurrency 설정이 있으면 같은 그룹의 이전 job이 끝날 때까지 대기한다. 이건 에러가 아니라 의도된 동작이지만, 착각하기 쉽다.
concurrency:
group: ${{ github.ref }}
cancel-in-progress: false # 이게 true면 이전 job 취소, false면 대기cancel-in-progress: true로 바꾸면 이전 job을 취소하고 새 job이 바로 시작된다.
마무리 — 순서대로 확인하면 대부분 해소된다
- GitHub Status 체크 (플랫폼 이슈 먼저 배제)
- Runner 온라인 상태 확인
- runs-on 라벨 오타 확인
- Runner group 권한 확인
- ARC 사용 중이면 controller 재시작
이 순서대로 체크하면 "Waiting for a runner..." 에러는 대부분 잡힌다. 플랫폼 장애가 아닌 이상 대기 상태가 10분 이상 지속되면 위 체크리스트를 돌리는 게 빠르다.
GitHub Actions 관련해서 secrets 관련 이슈는 GitHub Actions secrets 환경변수 undefined 에러 해결 글도 참고할 수 있다.
댓글 없음:
댓글 쓰기