
요약
안녕하세요, 당근 SRE팀 딜리버리 파트에서 일하고 있는 Uno(우노)예요. 딜리버리 파트는 Kubernetes 환경 기반의 사내 배포 플랫폼 Kontrol을 운영하고 GitHub Actions 중심의 전사 CI 시스템을 관리해요. 이번 글에서는 GitHub Actions를 운영하며 Job의 대기 현황과 Job을 실행 중인 Runner를 파악하기 위해 exporter를 만들고 개선한 과정을 소개할게요.
exporter를 소개하기에 앞서 GitHub Actions의 구조를 간단히 살펴볼게요. GitHub Actions에서는 push나 Pull Request 같은 이벤트가 발생했을 때 실행할 작업의 흐름을 Workflow로 정의해요. 하나의 Workflow는 테스트, 빌드처럼 여러 Job으로 나뉘어 각 Job은 Runner라는 실행 환경에 배정되어 실행되고 할당 가능한 Runner가 없으면 Job은 배정될 때까지 대기해요.
name: Simple # 1. Workflow: 자동화 작업 정의
on:
workflow_dispatch:
jobs:
run_shell_command: # 2. Job: Runner 배정 및 실행 단위
name: Actions are amazing
runs-on: arc-test-runner
steps: # 3. Step: 작업 실행 절차 및 명령
- name: Say hello
run: |
echo "Hello!"
GitHub Actions의 Job을 실행하는 Runner는 크게 GitHub이 관리하는 GitHub-hosted Runner와 GitHub 외부에서 운영하는 self-hosted Runner 두 가지로 나뉘어요. 당근은 Kubernetes 환경에서 직접 운영하는 self-hosted Runner를 주로 사용하고 이 Runner는 ARC(Actions Runner Controller)라는 Kubernetes 오퍼레이터로 관리해요.
ARC는 Runner Scale Set 단위로 Runner를 관리하고 대기 중인 Job 수에 맞춰 Runner 수를 조절해요. Runner Scale Set에는 Runner의 이미지와 리소스 및 최소, 최대 수를 설정할 수 있고 Workflow의 runs-on에 Runner Scale Set을 지정하면 해당 Runner에 Job이 배정돼요.

Runner 수가 자동으로 조절되지만 모든 Job이 즉시 실행되지는 않고 GitHub 장애가 발생하거나 Job 요청이 급증해 실행이 지연되면 Queued 상태로 표시돼요. ARC로 Runner를 운영하면서 가장 자주 받은 문의도 “GitHub Action이 Queued 상태로 실행되지 않아요.”였어요.

하지만 상황 파악을 위한 데이터가 부족해서 GitHub 상태 페이지에 공지가 올라오기를 기다리거나 ARC가 기본적으로 제공하는 메트릭으로 원인을 추측할 수밖에 없었어요.
ARC 기본 메트릭으로 Runner와 Job의 집계 현황은 볼 수 있지만 Runner를 기다리는 Job 개수와 대기 시간, 어떤 Job이 어느 Runner Pod에서 실행되는지는 파악하기 어려웠어요. 이런 정보를 확인할 수 있다면 Job 실행을 기다리는 개발자분들께 현재 상황을 더 명확하게 안내할 수 있을 거라고 생각했고 해결책을 찾던 중 Runner Pod에 Job 정보를 라벨로 추가하자는 ARC 이슈를 발견했어요. 하지만 이 방식은 컨트롤러 변경과 권한 추가가 필요해 적용까지 시간이 걸릴 수 있었고 라벨을 메트릭으로 수집하는 구성도 따로 마련해야 해서 다른 방법을 찾아야 했어요.
그래서 Runner Pod와 Job의 관계뿐만 아니라 대기 중인 Job까지 살펴볼 수 있도록 action-runner-job-exporter를 만들었어요. exporter는 Runner Pod에 Job 이름을 붙이는 Collector, Runner를 기다리는 Job을 추적하는 Webhook, Webhook의 상태를 저장하는 StateStore까지 세 개의 바이너리로 구성했어요. 지금부터 각 구성 요소를 만든 과정과 운영하며 개선한 내용을 소개할게요.

배경: ARC Runner가 생성되고 Job을 배정받기까지
Collector가 Runner와 Job을 어떻게 연결하는지 살펴보기 전에 ARC에서 Runner Pod가 생성되고 Job을 배정받는 과정을 먼저 알아볼게요.
- 각 Runner Scale Set의 Listener Pod는 GitHub과 세션을 맺고 새로운 Job 배정을 기다려요.
- 저장소에서 Workflow가 실행되면 GitHub은 각 Job의 runs-on에 맞는 Runner Scale Set에 Job을 배정해요.
- Listener는 배정된 Job과 최소·최대 Runner 설정을 바탕으로 필요한 Runner 수를 계산해서 EphemeralRunnerSet의 replicas를 변경해요.
- ARC가 필요한 수만큼 EphemeralRunner를 생성하고 GitHub에서 일회용 등록 설정(JIT config)을 받아와 Runner Pod를 띄워요.
- Runner Pod가 GitHub에 등록되면 GitHub은 해당 Runner에 Job을 배정해요.
- Job이 시작되면 Listener가 Job 배정 정보를 받아 해당 EphemeralRunner의 status 필드에 저장소와 Job 정보를 업데이트해요.
- Job이 끝나면 Runner 프로세스가 종료되고 ARC가 Runner 관련 리소스를 정리해요.

ARC가 필요한 수만큼 Runner를 생성하면 각 Runner에 어떤 Job을 배정할지는 GitHub이 결정해요. Runner Pod는 특정 Job을 위해 생성되지 않으므로 Pod 이름만으로는 어떤 Job이 배정되었는지 알 수 없고 Listener가 EphemeralRunner의 status를 갱신해야 배정된 Job을 확인할 수 있어요.
Collector: Runner Pod에 Job 이름 붙이기
exporter를 만든 목표는 개발자분들이 GitHub Actions의 상태를 문의하시기 전에 SRE가 GitHub Actions의 이상 징후를 먼저 파악하는 것이었어요. 그래서 가장 먼저 Runner Pod에서 어떤 Job을 실행하고 있는지 확인하고 싶었어요. Pod 라벨과 기존 메트릭에는 Job 정보가 없었지만 EphemeralRunner와 Runner Pod의 이름이 같다는 점을 이용하면 status에 기록된 Job 정보를 해당 Pod와 연결할 수 있다고 생각했어요.
이 아이디어로 Pod와 Job의 관계를 메트릭으로 확인할 수 있도록 첫 번째 바이너리인 Collector를 만들었어요. Collector는 Kubernetes informer로 EphemeralRunner의 생성, 변경, 삭제를 지켜보며 최신 상태를 메모리 캐시에 저장하고 이 캐시를 읽어 아래 메트릭을 제공해요.
arc_runner_job_info{namespace, pod, runner_name, repository, job_name, workflow_ref, workflow_run_id}Collector는 Job이 시작되어 status.jobRepositoryName이 채워진 Runner에 대해서만 이 메트릭을 제공해요. workflow_run_id 라벨은 여러 Job을 이어서 작업을 정의하는 Workflow를 가리키는 값이라 https://github.com/<org>/<repo>/actions/runs/<workflow_run_id>로 실행 페이지 링크를 바로 만들 수 있게 구성했어요.

Prometheus가 메트릭을 수집할 때 exporter Pod의 라벨과 이름이 겹쳐서 Runner Pod의 이름은 exported_pod에, Namespace는 exported_namespace에 담겨 있어요. 이 라벨을 컨테이너의 CPU, 메모리, 네트워크 사용량 메트릭(container_.*)에 있는 pod, namespace 라벨과 연결하면 사용량에 저장소와 Job 이름을 붙일 수 있어요. 덕분에 대시보드에서 실행된 Job마다 Runner Pod를 연결해서 Job의 리소스 사용량을 바로 확인할 수 있게 되었어요.

다만 Job이 종료되어도 EphemeralRunner가 정리되기 전까지는 status에 Job 정보가 남아있어요. 그래서 메트릭에 보이는 Job은 지금 실행 중인 Job이 아니라 ‘Runner가 배정받은 Job’으로 해석해야 해요.
Webhook: Runner를 기다리는 Job 가시화하기
status 필드는 Runner가 Job을 배정받고 실행을 시작한 뒤에 채워지기 때문에 GitHub Queue에서 Runner를 기다리는 Job은 Collector로 확인할 수 없었고 대기 중인 Job이 얼마나 쌓여있는지도 파악하기 어려웠어요. 그래서 GitHub Organization에 workflow_job 웹훅을 설정하고 Job 상태가 바뀔 때마다 이벤트를 받는 두 번째 바이너리, Webhook을 만들었어요. 웹훅 이벤트는 ARC Listener를 거치지 않고 GitHub에서 직접 전달되기 때문에 Listener에 문제가 생겨도 웹훅이 정상적으로 전달된다면 대기 중인 Job을 확인할 수 있어요.

workflow_job 이벤트로 확인할 수 있는 주요 Job 상태는 다음과 같고 일반적으로 Job은 queued → in_progress → completed 순서로 진행돼요.
- waiting: 배포 환경 승인 등 보호 규칙을 기다리는 상태로 Runner를 기다리는 상태와 구분해요.
- queued: 실행을 기다리는 상태로 보통 Runner 할당을 기다려요.
- in_progress: Runner에 배정되어 실행 중인 상태예요.
- completed: 실행이 종료된 상태로 성공, 실패, 취소를 모두 포함해요.
Webhook은 job_id를 키로 Job 상태를 메모리에 저장하고 이를 집계해 메트릭을 제공해요.
- github_workflow_jobs_queued: 실행을 기다리는 Job 수
- github_workflow_jobs_in_progress: 실행 중인 Job 수
- github_workflow_job_queued_seconds: Job이 생성된 시각
- github_workflow_job_queue_duration_seconds: Job이 Runner를 배정받기까지 기다린 시간을 담은 히스토그램
github_workflow_job_queued_seconds에는 대기 시간 대신 Job이 생성된 시각을 Unix time으로 담았어요. time() - github_workflow_job_queued_seconds로 현재 대기 시간을 계산할 수 있어서 exporter가 값을 계속 갱신할 필요가 없고 Job이 Runner에 배정되어 실행을 시작하면 해당 Job은 메트릭에서 사라져요.

GitHub 웹훅 이벤트는 순서대로 도착한다는 보장이 없어요. 그래서 Job 상태가 queued → in_progress → completed 방향으로만 변경된다는 전제로 이미 in_progress, completed인 Job에 늦게 도착한 queued 이벤트는 무시해요. 완료된 Job도 상태 맵에서 바로 삭제하면 늦게 도착한 이벤트 때문에 새로운 대기 Job으로 잘못 집계될 수 있어요. 그래서 완료된 Job은 바로 삭제하지 않고 일정 시간 동안 완료 표시(tombstone)로 남겨두었어요.
Webhook으로 대기 중인 Job이 얼마나 쌓여 있는지 확인하고 Job이 대량으로 밀릴 때는 메트릭을 통해 정확한 상태를 공유할 수 있었어요.

이후에 일정 시간 이상 대기하는 Job 수가 임계치를 넘으면 알림이 오도록 설정했어요. 더하여 Runner Scale Set의 Runner 수가 maxRunners의 90%에 도달할 때도 알림을 보내 ARC 설정으로 인한 병목을 살펴볼 수 있게 했어요.


StateStore: Webhook이 재시작해도 상태를 잃지 않게
처음 만든 Webhook은 Job 상태를 메모리에만 저장해서 배포하거나 재시작하면 대기 중이던 Job의 상태를 잃어버렸어요. 상태를 S3에 저장해 두고 복원하는 방법도 있지만 Webhook은 GitHub 이벤트를 받기 위해 인터넷에 노출되어 있어서 S3 권한을 부여하고 싶지 않았어요.
그래서 세 번째 바이너리인 StateStore를 만들었어요. Webhook이 침해되더라도 공격자가 S3 권한을 직접 사용하기 어렵도록 S3 권한은 사내망에 있는 StateStore에만 부여하고 스냅샷 저장을 맡겼어요.

롤아웃 중에는 일시적으로 이전 버전과 새 버전 Pod가 함께 실행되기 때문에 S3 조건부 쓰기(ETag / If-Match)로 서로의 저장 내용을 덮어쓰지 않게 했어요.
운영 개선: 잘못 집계된 Job 상태 바로잡기
#1 completed Job이 queued로 집계된 문제
어느 날 Runner를 오래 기다리는 Job이 72개라는 알림이 울렸지만 실제로는 모두 몇 시간 전에 완료된 상태였어요. 원인을 추적해보니 Webhook이 재시작되면서 오래된 스냅샷을 복원했고 이미 완료된 Job이 대기 중인 것으로 집계된 거였어요.
당시 Webhook은 진행 중인 Job의 상태와 완료된 Job의 tombstone, 중복 제거에 사용하는 Delivery ID(X-GitHub-Delivery)의 보관 기간과 스냅샷 복원 유효기간을 모두 기본값이 6시간인 --webhook-ttl 하나로 관리하고 있었어요. 그 결과 상태 맵에 6시간 치 기록이 쌓였어요. 스냅샷 크기 상한은 진행 중인 Job의 상태만 저장할 것을 고려해 8MiB로 여유 있게 설정했는데 스냅샷이 이 상한을 넘으면서 문제가 발생했어요.
- 스냅샷 저장 중단: Delivery ID와 tombstone이 쌓이면서 스냅샷 크기가 8MiB로 늘었고 이후 스냅샷 저장이 중단되었어요.
- Webhook 재시작: 상태 맵을 메모리에 보관하던 Webhook Pod가 메모리 limit 0.2GB를 넘겨 OOMKilled 됐어요.
- 오래된 상태 복원: 새 Pod는 2시간 44분 전에 저장된 스냅샷에서 Job 상태 16,097개를 복원했어요. 스냅샷 복원 유효기간이 6시간이어서 오래된 스냅샷이지만 복원 대상에 포함됐어요.
- 완료된 Job이 대기 중으로 집계: 스냅샷 저장이 중단된 뒤 수신한 completed 이벤트는 종료된 Pod의 메모리에만 남아 있었어요. 새 Pod에는 이 이벤트가 반영되지 않아 이미 완료된 Job을 queued 상태로 집계했어요.

잘못 복원된 Job은 이후 상태를 갱신할 이벤트가 오지 않아 대기 시간만 늘어났고 이후에 보관 기간인 6시간이 지나 상태가 한꺼번에 삭제되면서 알림도 해제됐어요.
데이터별로 보관 기간 분리하기
같은 문제가 반복되지 않도록 데이터 종류에 따라 보관 기간을 나누고 스냅샷 복원 유효기간도 별도로 설정했어요. 진행 중인 Job은 오래 추적할 수 있도록 보관하되 tombstone과 Delivery ID는 보관 기간을 줄였어요. 스냅샷은 오래될수록 실제 상태와 달라질 가능성이 커지기 때문에 복원 유효기간을 짧게 설정했어요.
- --webhook-ttl 6시간: 진행 중인 Job
- --tombstone-ttl 1시간(현재 3시간): completed Job과 waiting Job의 tombstone
- --dedup-ttl 10분: Delivery ID (X-GitHub-Delivery)
- --snapshot-max-age 10분: 스냅샷 복원 유효기간
알림을 받았을 당시 상태 맵의 항목 16,097개 중 진행 중인 Job은 175개뿐이었고 나머지 대부분은 tombstone이었어요. 그래서 tombstone 보관 기간을 1시간으로 줄이자 스냅샷 크기도 8MiB에서 약 0.66MiB로 줄어드는 걸 확인할 수 있었어요.
그리고 이벤트 카운터만으로는 전송이 끊긴 것인지, 원래 이벤트가 적은 시간대인지 구분하기 어려웠어요. 그래서 스냅샷 저장이나 웹훅 수신이 멈춘 상황을 살펴볼 수 있도록 마지막 스냅샷 저장 시각, 시작 시 복원한 Job 수와 스냅샷의 저장 경과 시간, 마지막 웹훅 수신 시각을 메트릭으로 추가했어요.
#2 실패한 웹훅 이벤트 재전송하기
GitHub은 실패한 웹훅을 자동으로 재전송하지 않아요. Webhook이 내려가 있거나 일시적인 네트워크 문제로 in_progress나 completed 이벤트를 놓치면 해당 Job은 보관 기간인 6시간 동안 대기 중이거나 실행 중인 상태로 남을 수 있어요.
이 점을 보완하기 위해 StateStore가 GitHub App으로 5분마다 Organization 웹훅의 전송 기록을 확인하도록 했어요. 최근 30분 안에 전송에 실패한 workflow_job 이벤트 중 in_progress와 completed는 재전송을 요청해요. queued와 waiting은 늦게 도착해 상태를 잘못 집계할 가능성을 고려해 제외했어요. 같은 이벤트가 중복 처리되지 않도록 Delivery ID도 확인해요.
#3 GitHub의 실제 상태로 Webhook의 Job 상태 바로잡기
재전송만으로 해결되지 않는 경우도 있었어요. 이미 성공한 Job 수십 개가 queued 상태로 남아 있는 일이 발생했는데 queued 이벤트가 Job 생성 후 한 시간 넘게 늦게 도착하고 그사이 당시 보관 기간이 1시간이었던 tombstone이 삭제되어 Webhook이 이를 새로운 대기 Job으로 인지한 것이 문제였어요.
같은 시각 GitHub Status에서 웹훅 전송 지연과 관련된 장애를 확인하며 원인은 파악했지만 이미 잘못 집계된 상태를 바로잡을 방법이 필요했어요. 그래서 일정 시간 동안 상태가 바뀌지 않은 Job은 리컨사일(reconcile)을 통해 GitHub의 실제 상태와 동기화하기로 했어요.
- Webhook은 1분마다 10분 넘게 이벤트가 없는 queued, in_progress Job의 상태를 StateStore를 통해 Actions API로 확인해요. GitHub에서 Job이 완료된 것으로 확인되면 completed로, 실행 중이면 in_progress로, 승인을 기다리는 상태면 waiting으로 상태를 갱신해요. 상태는 queued → in_progress → completed 방향으로만 변경된다는 전제를 지키며 여전히 queued라면 상태를 유지해 실제 대기 중인 Job의 알림은 그대로 유지해요. 조회하는 사이 웹훅 이벤트가 도착하면 해당 이벤트에 따라 상태를 업데이트해요.
- StateStore가 사용하던 GitHub App에 Actions: read 권한을 추가해서 조회해요. rate limit을 고려하여 매 주기마다 가장 오래전에 확인한 Job부터 최대 50개를 조회해서 Job 조회는 시간당 최대 3,000번으로 제한해요.
tombstone 보관 기간 늘리기
리컨사일 배포 후 5분 동안 완료된 Job 244개가 정리되었고 오래 대기 중이던 Job은 30개에서 4개로 줄었어요. 하지만 당일 오후에도 queued 이벤트가 70~112분씩 늦게 도착하면서 리컨사일 대상이 되기 전까지 약 10분 동안 Job 30여개가 알림에 걸렸어요. 그래서 --tombstone-ttl 기본값을 1시간에서 3시간으로 늘리고 3시간보다 늦게 도착하는 이벤트로 잘못 집계된 상태는 리컨사일로 정리하도록 개선했어요.

활용 사례: 메트릭으로 적절한 Runner 선택하고 병목 찾기
#1 Job별 사용량을 고려한 Runner 선택
Collector로 Runner Pod의 리소스 사용량에 Job 이름을 붙이면서 Job마다 실제로 사용하는 CPU와 메모리를 확인할 수 있게 되었어요. 이 사용량을 Runner에 설정된 리소스 요청량(request)과 비교하면 각 Job이 필요한 크기의 Runner를 사용하고 있는지 판단할 수 있어요.
필요 이상으로 큰 Runner를 사용하면 리소스가 낭비될 뿐 아니라 리소스를 확보하는 데 시간이 걸려 Pod 스케줄링이 늦어질 수도 있어요. 그래서 Job에 맞는 Runner를 선택할 수 있도록 이 데이터를 바탕으로 Job별 권장 Runner를 보여 주는 대시보드도 운영하고 있어요.

#2 GitHub 장애가 아닌 ARC 설정으로 인한 지연 탐지
Runner를 기다리는 Job이 계속 쌓이면서 대기 시간 알림이 울렸고 Webhook Queue 대시보드에서도 대기 중인 Job이 늘어나는 것을 확인할 수 있었어요.
먼저 GitHub 장애 여부를 확인했지만 공지된 장애는 없었고 Runner 등록 설정(JIT config)을 가져오는 호출의 중앙값도 0.57초로 평소와 비슷했어요. 그래서 ARC 쪽을 살펴보니 Runner의 생성과 정리를 담당하는 EphemeralRunner 컨트롤러의 작업 큐(workqueue_depth)가 평소보다 훨씬 높아져 있었어요.

작업을 처리하는 worker 수(controller_runtime_active_workers)는 6시간 동안 2에 머물러 있었는데 이 값은 동시 처리 수 설정인 runnerMaxConcurrentReconciles의 기본값(0.12.x 기준)이에요. 작업 처리 시간도 p99 기준 0.9초에서 8~10초로 늘어나 있었어요. worker가 두 개뿐인 상황에서 GitHub 호출 지연까지 발생하자 컨트롤러가 작업을 제때 처리하지 못하고 있음을 확인했어요.

이 병목 때문에 새 Runner를 만드는 작업이 큐에서 밀리면서 Pod 생성도 늦어졌어요. 한 Runner Scale Set에서는 생성을 기다리는 Runner가 258개였지만 Pod는 약 150개뿐이었어요. Runner 정리도 지연되면서 이미 종료된 Pod 95개와 삭제 중인 Runner 55개가 maxRunners 한도를 계속 차지하고 있었어요.
컨트롤러의 처리량을 늘리기 위해 runnerMaxConcurrentReconciles를 2에서 5로 상향 조정하니 약 10분 만에 컨트롤러 큐는 669에서 233으로, 대기 Job은 380에서 168로 줄었고 Runner Scale Set의 대기 Runner도 224에서 61로 감소했어요. 작업 처리 시간의 p99는 여전히 11초로 높았지만 동시 처리 수를 늘린 뒤 밀려 있던 작업이 줄어들었어요. Webhook 메트릭으로 Job 대기 상황을 파악하고 ARC 컨트롤러 메트릭을 함께 살펴본 덕분에 병목이 컨트롤러의 처리량에 있다는 점을 짚을 수 있었어요.

마무리: 보이지 않던 Job의 상태를 살펴볼 수 있게 되기까지
처음에는 GitHub Actions를 ARC로 직접 운영하더라도 GitHub에 의존하는 부분이 커서 장애가 발생했을 때 개발자분들께 상황을 안내하고자 메트릭 수집을 목표로 시작했어요. 그런데 Job의 상태를 살펴볼 수 있게 되면서 장애 안내뿐 아니라 Runner 사용량을 파악하고 지연 원인을 찾아 병목을 개선하는 데에도 활용하고 있어요.
GitHub Actions와 ARC를 운영하며 Job과 Runner의 상태를 파악하기 위해 비슷한 고민을 하고 계신 분들께 이 글이 도움이 되었으면 좋겠어요. 읽어주셔서 감사합니다.
GitHub Actions 모니터링의 빈칸: Exporter로 ARC Runner 관측하기 was originally published in 당근 기술 블로그 on Medium, where people are continuing the conversation by highlighting and responding to this story.