GitHub Actions 러너, 등록됐는데 왜 job을 못 받을까?

읽는 시간 약 9분 · CI 운영 판단 가이드

핵심 요약

• 등록됐다는 표시는 job 실행 가능성을 보장하지 않습니다. GitHub는 등록과 job 실행에 서로 다른 버전 기준을 둡니다.
• 버전 2.329.0은 등록 또는 재등록을 위한 기준입니다. 계속 job을 실행하려면 runner release를 최신 상태로 유지해야 하며, 이 숫자를 영구적인 실행 최소 버전으로 보면 안 됩니다.
• 각 version의 registration_deprecates_at과 runtime_deprecates_at을 별도로 조회하세요. 현재 실행 지원일은 release에 따라 이동합니다.
• API 응답만으로 실제 업무가 정상이라고 판단하지 마세요. 해당 runner에서 최근 대표 job이 실행됐는지, 업데이트 경로와 담당자가 준비됐는지도 확인해야 합니다.
• 지원 날짜 조회 실패, 현재 version 미확인, 대표 job 증거 부재 중 하나라도 있으면 상태는 ready가 아니라 hold/unknown입니다.

목차

등록과 실행은 서로 다른 관문입니다

GitHub Actions에서 self-hosted runner는 조직이나 저장소에 등록한 다음 workflow job을 수행합니다. 운영자가 목록에서 runner를 볼 수 있다는 사실은 첫 관문을 통과했다는 뜻에 가깝고, 현재 버전이 job을 계속 수행할 수 있다는 증거와는 다릅니다.

GitHub의 2026년 6월 안내는 새 아키텍처에서 runner를 설정하거나 (재)등록하려면 2.329.0 이상이어야 한다고 설명합니다. 동시에 실제 job을 계속 실행하려면 새 runner release를 공개된 뒤 30일 이내에 설치해야 한다고 안내합니다. 따라서 2.329.0은 등록 기준이지 고정된 job 실행 기준이 아닙니다. GitHub의 최소 버전 시행 안내에서 두 기준을 나눠 확인할 수 있습니다.

이 구분은 이미 운영 중인 runner에도 중요합니다. 최신 등록 기준보다 낮은 runner는 새로 등록하거나 재등록하지 못할 수 있고, 등록된 상태더라도 현재 job 실행 기준보다 오래된 runner는 job 수행을 멈출 수 있습니다. 그러므로 화면의 online/registered 상태 하나만으로 fleet을 운영 가능하다고 판정하지 않는 편이 안전합니다.

runner가 등록돼도 job을 못 받을 수 있는 이유

버전 지원은 runner가 job을 받을 자격을 판단하는 중요한 항목이지만, 유일한 진단 항목은 아닙니다. 오래된 runner version, 업데이트 서비스에 닿지 않는 네트워크, workflow의 runner group·label 조건, 실제 최근 job 결과는 각각 다른 종류의 증거입니다. 한 항목의 성공을 다른 항목의 통과로 대신하면 원인을 놓칠 수 있습니다.

자동 업데이트가 켜져 있어도 update service에 접근할 수 있어야 합니다. GitHub 안내는 runner가 업데이트 서비스에 도달할 수 있을 때 자동 업데이트가 30일 요구사항을 충족한다고 설명합니다. 업데이트가 꺼져 있다면 운영자가 정기적으로 설치해야 합니다. 새 release가 제공된 뒤 정해진 기간 안에 업데이트되지 않은 경우 job queueing이 중단될 수 있고, 중요한 보안 업데이트가 나오면 적용될 때까지 queueing이 일시 중지될 수 있습니다. 이는 “자동 업데이트를 켰으니 더 확인할 필요가 없다”는 뜻이 아닙니다.

반대로 지원 일정이 유효한데도 job이 대기한다면 runner group 접근 정책이나 workflow의 label 조건, runner 상태와 job 기록을 따로 살펴보세요. GitHub의 runner 관리 문서는 runner group과 label을 이용하는 방식을 설명합니다. version 점검은 문제 범위를 좁히는 한 축이지 모든 job 지연을 설명하는 만능 진단은 아닙니다.

읽기 전용 API로 version 증거 모으기

조직 runner 목록 API는 등록된 runner와 version을 확인하는 출발점입니다. runner version deprecation API는 특정 version의 등록·실행 지원 종료 시점을 돌려줍니다. GitHub는 이 API를 저장소·조직·enterprise 범위에서 제공한다고 안내합니다. 아래 예시는 조직 범위의 읽기 요청입니다. ORG와 VERSION은 실제 값을 넣되, 출력에 runner 이름이나 내부 주소를 포함해 외부 문서·티켓에 복사하지 마세요.

gh api -H 'Accept: application/vnd.github+json' \
  -H 'X-GitHub-Api-Version: 2026-03-10' \
  /orgs/ORG/actions/runners

gh api -H 'Accept: application/vnd.github+json' \
  -H 'X-GitHub-Api-Version: 2026-03-10' \
  /orgs/ORG/actions/runners/deprecations/VERSION \
  --jq '{runner_version, registration_deprecates_at, runtime_deprecates_at}'

두 번째 endpoint와 응답 필드 이름은 GitHub의 runner version deprecations API 안내에, 조직 단위 endpoint 및 권한 조건은 자가 호스팅 runner REST API 문서에 나와 있습니다. 현재 GitHub 문서는 조직 runner 조회에 조직 관리자 접근을 요구하며, fine-grained token에는 조직의 “Self-hosted runners” 읽기 권한을 안내합니다. 접근이 거부되면 권한 있는 관리자에게 최소 읽기 범위를 요청하세요. 403이나 빈 결과를 지원 날짜가 안전하다는 뜻으로 해석하면 안 됩니다.

API 버전과 endpoint는 바뀔 수 있으므로 실행 전에 원문 문서에서 현재 요청 경로와 API version을 다시 확인하세요. 인증 정보는 GitHub CLI가 사용하는 승인된 인증 저장소를 이용하고, 터미널 출력·스크린샷·공유 로그에 token을 남기지 마세요.

5칸 Runtime Readiness Card

fleet 전체를 “정상” 한 단어로 표시하는 대신, 다섯 칸의 최소 증거를 runner group 또는 승인된 운영 단위별로 정리해 보세요. 내부 runner 이름은 필요한 시스템에서만 유지하고, 공유용 카드에는 별칭이나 집계값을 쓰는 편이 좋습니다.

모바일에서는 표를 좌우로 밀어 확인하실 수 있습니다. 공유용 카드에는 조직명, 개인 runner 이름, token, 내부 URL, 원시 로그를 넣지 마세요.

예를 들어 inventory에 version 2.329.0이 보인다면 등록 관문에 필요한 기준을 충족할 수 있다는 뜻이지, 현재 job 실행 기준도 통과했다는 뜻은 아닙니다. API가 실행 종료일을 돌려주지 않거나, 대표 job이 확인되지 않았다면 해당 칸을 “미확인”으로 남기세요. 확인되지 않은 날짜를 계산하거나 임의의 최신 최소 version으로 채우지 않는 것이 중요합니다.

ready·update·hold 결정 기준

상태는 색깔보다 다음 행동을 결정하는 데 써야 합니다. 팀마다 배포 주기와 허용 가능한 여유 기간이 다르므로, “마감 7일 전이면 경고”처럼 근거 없는 보편 숫자를 두기보다 필요한 업데이트·시험 시간을 반영한 내부 기준을 정하세요.

모바일에서는 표를 좌우로 밀어 확인하실 수 있습니다.

작은 파일럿과 중단 조건

1. 적용 범위를 먼저 고정합니다. 제품 유형, 조직 또는 저장소 범위, runner group 별칭과 대표 workflow 하나를 정합니다.
2. 읽기 전용으로 현재 상태를 수집합니다. inventory의 version과 deprecation API의 두 지원 날짜를 같은 조회 시각과 함께 보관합니다.
3. 대표 job을 재현합니다. 실제 업무를 대표하되 외부 상태를 바꾸지 않는 검증 workflow를 선택하고, runner 선택 조건과 완료 결과를 확인합니다.
4. 업데이트 경로를 확인합니다. 자동 업데이트 설정, update service 연결, 수동 설치 담당자와 변경 창을 확인합니다.
5. 증거가 모두 있을 때만 다음 범위를 정합니다. 누락이 있으면 담당자·재조회 시각·중단 범위를 카드에 남기고, 자동 확대를 보류합니다.

대체 runner를 검토할 때도 단순히 job이 빨리 끝나는지로 판단하지 마세요. 저장소 접근 권한, secret 전달, 네트워크 구간, 필요한 도구와 데이터 접근이 새 runner에서도 의도한 범위로 제한되는지 별도로 확인해야 합니다.

FLOWIT 실무 관점: 권한·신뢰성·운영 증거를 연결하세요

자가 호스팅 runner의 버전 관리는 패치 작업이면서 동시에 자동화의 실행 경계를 다루는 일입니다. 오래된 runner가 job을 받지 못하면 큐 지연과 업무 중단으로 이어질 수 있지만, 긴급 복구를 위해 더 넓은 권한의 다른 runner에 무작정 옮기면 위험을 키울 수 있습니다. 따라서 업데이트 날짜만 보지 말고 어떤 workflow가 어떤 권한으로 어느 runner에서 실행됐는지를 확인 가능한 범위에서 연결해야 합니다.

배포 artifact의 출처를 확인하는 작업은 runner version readiness와 서로 대체되지 않습니다. GitHub Artifact Attestation 배포 전 검증은 결과물의 출처를 확인하고, 이 카드의 목적은 job을 수행하는 runner version과 실제 실행 증거를 확인하는 것입니다. 또한 재사용 workflow 권한 경계 점검은 caller·called workflow 간 권한 전달을 살펴봅니다. 문제가 났을 때 운영 변경을 수용하는 일반 절차는 대표 업무를 재실행하는 업그레이드 수용 시트와 연결해 보실 수 있습니다.

FLOWIT의 운영 기준은 간단합니다. 지원 일정은 최신 API에서, 실행 가능성은 대표 job에서, 확대 책임은 owner와 중단 조건에서 각각 확인하세요. 어느 한 쪽도 다른 증거를 대신하지 않습니다.

자주 묻는 질문

runner가 2.329.0이면 계속 job을 실행할 수 있나요?

그 숫자만으로는 판단할 수 없습니다. GitHub는 2.329.0을 설정·등록 또는 재등록을 위한 기준으로 설명하고, 실제 job 실행 기준은 새 runner release에 따라 이동한다고 안내합니다. 현재 version의 실행 지원일과 대표 job을 따로 확인하세요.

자동 업데이트를 켜면 version 확인을 생략해도 되나요?

아닙니다. GitHub 안내상 자동 업데이트는 runner가 update service에 도달할 수 있을 때 30일 요구사항을 충족합니다. 연결 상태와 최근 대표 job을 확인하고, 보안 업데이트가 적용됐는지도 운영 절차에 포함하세요.

등록된 runner가 job을 못 받으면 version 문제인가요?

가능성 중 하나일 뿐입니다. 지원 일정 외에도 runner 상태, group 접근 정책, workflow의 label 선택, 최근 실행 결과를 구분해 보세요. API 오류는 version이 안전하다는 증거가 아닙니다.

이 일정이 GitHub Enterprise Server에도 그대로 적용되나요?

2026년 9월 28일 날짜 변경 공지는 해당 변경이 GitHub Enterprise Cloud에 관한 것이며 GitHub Enterprise Server에는 영향을 주지 않는다고 설명합니다. Data Residency에는 별도 일정이 안내됐습니다. 환경별 적용 여부는 최신 공식 공지와 실제 제품 범위를 기준으로 판단하세요.

runner inventory와 지원 날짜 조회가 실패하면 어떻게 해야 하나요?

상태를 unknown/hold로 남기고, 적절한 읽기 권한이 있는 담당자에게 재조회를 요청하세요. 누락된 값을 추정하지 말고 대표 job 실행과 업데이트 책임자가 확인될 때까지 범위를 확대하지 않는 편이 안전합니다.

참고 자료

• GitHub Changelog — Self-hosted runner version enforcement date has moved: GitHub Enterprise Cloud의 시행일 변경, 등록과 실행 기준의 차이, Data Residency 및 GitHub Enterprise Server의 범위를 확인했습니다.
• GitHub Changelog — Minimum version enforcement timeline for self-hosted runners: 2.329.0의 등록 용도, release별 실행 version 업데이트 요구, 자동 업데이트의 연결 조건과 queueing 중단 설명을 확인했습니다.
• GitHub Changelog — Early September 2026 updates: version별 등록·실행 지원 종료 시점을 조회하는 deprecation API와 응답 필드를 확인했습니다.
• GitHub Docs — REST API endpoints for self-hosted runners: 조직 runner inventory, version 정보, 조직 단위 deprecation endpoint와 읽기 권한 조건을 확인했습니다.
• GitHub Docs — Managing self-hosted runners: runner group과 label 기반 운영·선택 경계를 확인했습니다.

공식 문서는 2026년 10월 27일 KST에 다시 확인했습니다. 시행 일정과 API 설명은 바뀔 수 있으므로 실제 업데이트 전에는 최신 원문과 조직의 현재 응답을 확인하세요. 이 글의 점검 카드는 운영 결정을 돕는 기록이며, 특정 fleet의 상태를 대신 진단하지 않습니다.