GitHub Actions의 필수 체크를 GitHub 호스트 러너에서 자기 기기의 자체 호스팅 러너로 옮길 때, runs-on 한 줄만 바꾸면 끝나지는 않았다. 내가 기록에서 확인한 두 저장소에서는 그 한 줄이 라벨 설계, 린터 거부, 호스트 도구 누락에서 걸렸고, 별개로 커밋 상태 게시 한 건이 422로 거부됐다.

이 글은 같은 날, 같은 Windows 호스트의 WSL 러너로 필수 체크 harness/checks를 옮긴 두 작업을 다룬다. 기록 두 건이 서로 다른 저장소의 일이라서 이 글에서는 "첫째 저장소"와 "둘째 저장소"로 부르고, 수치와 사건을 섞지 않는다. 옮기기 전 점검, 성공 근거, 한계, 그리고 다음에 쓸 점검표까지 다루며, 러너 등록 절차나 호스트 설치 방법은 다루지 않는다.

한 줄만 바꾸면 된다는 생각이 깨진 곳

두 저장소 모두 바뀐 코드는 작았다. 첫째 저장소는 파일 2개, 6줄 추가, 1줄 삭제(2 files changed, 6 insertions(+), 1 deletion(-))였고, 둘째 저장소는 최종적으로 파일 1개, 1줄 추가, 1줄 삭제였다. 그런데 작은 변경이 지나가는 길에서 아래 네 가지가 깨졌거나 거부됐다.

자체 호스팅 러너로 옮길 때 깨진 것들: 증상, 원인, 처리, 해당 저장소
저장소증상원인처리
둘째로컬 actionlint가 종료 1로 거부(출력 16줄)사용자 지정 라벨 wsl과 호스트 라벨을 모르는 라벨로 취급라벨을 [self-hosted, Linux, X64]로 줄임
둘째Tests 단계에서 jq: command not found호스트에 jq가 없었고 선행 조건 도구 목록에도 없었음호스트에 jq 설치, 코드는 그대로 두고 같은 머리를 다시 실행
첫째상태 게시 422target_url이 로컬 파일 주소였다고 작업 그래프에 적혀 있음target_url을 PR 주소(https)로 바꿔 같은 머리, 같은 컨텍스트로 재게시
첫째새 설정 파일이 저장소의 허용 목록 .gitignore에 무시됨허용 목록 방식의 무시 규칙git add -f로 올림

누가 무엇을 했는지도 먼저 적어 둔다. 워크플로 파일은 내가 목표를 지시한 코딩 에이전트가 작성했고, 다른 계열의 리뷰 모델이 검토했다. 적용은 실행 에이전트(run-task)가 맡았다. 상태 게시와 CI 실행 확인을 누가 했는지는 이 글이 읽은 기록 범위에서 확인되지 않는다. 내가 한 일은 목표 지시이고, 이 글에서 "바꿨다"나 "재실행했다"는 표현은 기록에서 그렇게 확인했다는 뜻이다.

runs-on 라벨: 두 저장소가 다르게 갔다

GitHub 문서에 따르면 자체 호스팅 러너는 등록될 때 self-hosted, 운영체제, 아키텍처 라벨을 자동으로 받고, 사용자 지정 라벨도 붙일 수 있다. runs-on에 여러 라벨을 적으면 그 라벨을 모두 가진 러너만 작업을 받을 수 있다. GitHub Docs의 Using self-hosted runners in a workflow(조회 2026-11-05)가 이를 설명한다.

두 저장소 모두 기준은 runs-on: ubuntu-latest였다. 기록에 따르면 호스트 쪽 영수증은 두 러너 모두에 self-hosted, Linux, X64, wsl, 호스트를 가리키는 라벨이 달렸다고 적는다. 선택은 여기서 갈렸다.

두 저장소의 runs-on 설계 비교
구분첫째 저장소둘째 저장소
최종 runs-on라벨 다섯 개라벨 세 개 [self-hosted, Linux, X64]
actionlint 설정 파일새 .github/actionlint.yaml에 두 라벨 선언없음(대안으로 검토했으나 채택하지 않음)
변경 규모2 files changed, 6 insertions(+), 1 deletion(-)1 file changed, 1 insertion(+), 1 deletion(-)
actionlint 결과1.7.12 종료 0, 출력 없음처음 종료 1, 보정 뒤 종료 0
러너에서 CI 결과PR 머리 success첫 실행 jq로 실패, 같은 머리 재실행 success

첫째 저장소는 runs-on을 [self-hosted, Linux, X64, wsl, <호스트 라벨>]로 바꿨다(<호스트 라벨>은 호스트를 가리키는 라벨의 자리표시자다). 둘째 저장소도 처음에는 같은 다섯 개를 적었다.

- runs-on: ubuntu-latest
+ runs-on: [self-hosted, Linux, X64, wsl, <호스트 라벨>]

아래 그림은 두 저장소가 고른 runs-on 라벨을 나란히 놓고 비교한다.

두 열로 나눈 비교 그림이다. 왼쪽 첫째 저장소는 runs-on에 wsl과 호스트 라벨까지 포함한 라벨 다섯 개를 적었고, 새 actionlint 설정 파일에 두 라벨을 선언했으며, 러너에서 PR 머리의 CI 결과가 success였다. 오른쪽 둘째 저장소는 처음에는 다섯 개를 적었다가 self-hosted, Linux, X64 세 개만 남겼다. 이 칸이 강조되어 있다. actionlint 선언은 대안으로 검토만 하고 채택하지 않았으며, 러너에서 첫 실행은 jq 때문에 실패했고 같은 머리를 다시 실행하자 success가 나왔다.
두 저장소는 같은 기준에서 출발했지만 라벨 수와 actionlint 선언 여부를 서로 다르게 골랐고, 어느 쪽이 낫다는 판정은 기록에 없다는 것이 이 비교의 요점이다.

기록에 있는 해석을 하나 옮긴다. 첫째 저장소 기록은 둘째 저장소가 같은 날 최소 라벨만 썼다는 점을 작업 그래프가 인지했는데도 첫째 저장소가 라벨 다섯 개와 actionlint 선언을 유지했다고 적는다. 어느 쪽이 낫다는 판정은 기록에 없다. 뒤의 한계 절에서 이 선택의 트레이드오프를 내 추정으로 따로 적는다.

actionlint가 사용자 지정 라벨을 거부했다

둘째 저장소에서 코딩 에이전트의 첫 페이로드는 라벨 다섯 개짜리 runs-on이었다. 로컬 actionlint가 종료 1로 거부했고, 출력은 16줄이었다. 이유는 라벨 wsl과 호스트 라벨을 모르는 라벨로 본 것이다. 다른 계열의 리뷰 모델도 이 점을 막았다. 점수는 correctness 3, coverage 6, maintainability 8, safety 9, integration 3이었고 blocker F1은 "actionlint rejects custom labels"였다.

이 동작은 actionlint 문서와 맞는다. actionlint의 Checks 문서(조회 2026-11-05)는 자체 호스팅 러너에 사용자 지정 라벨을 붙이면 actionlint가 그 라벨을 모르므로 설정 파일에 적어야 한다고 설명한다. 같은 문서의 예제 주석은 프리셋 라벨 [self-hosted, linux, x64]를 정상으로, 선언하지 않은 gpu 라벨을 오류로 표시한다. 설정 파일의 위치와 형식은 actionlint의 Configuration 문서(조회 2026-11-05)에 있다. .github 디렉터리의 actionlint.yaml에 self-hosted-runner의 labels를 적는다.

문서가 말하는 방식은 첫째 저장소가 택한 길과 같다. 첫째 저장소는 새 .github/actionlint.yaml에 두 라벨(wsl과 호스트 라벨)을 선언했다. 아래는 그 구조를 자리표시자로 쓴 예이며, 실제 파일의 주석 문구는 옮기지 않았다.

self-hosted-runner:
  labels:
    - wsl
    - <호스트 라벨>

그 파일은 저장소의 허용 목록 .gitignore에 무시되었기 때문에 git add -f로 올렸다. 기록은 같은 허용 목록 때문에 harness-checks.yml도 무시되지만 이미 추적되는 선례가 있고, 소유 파일 변경은 없다고 적는다. 첫째 저장소의 로컬 점검은 actionlint 1.7.12가 종료 0에 출력 없음이었다.

둘째 저장소는 다른 처리를 골랐다. 코딩 에이전트가 1회 보정으로 라벨을 [self-hosted, Linux, X64]로 줄였다. 기록이 적은 이유는 둘이다. 거부된 것이 사용자 지정 라벨 두 개뿐이었고, 설정 파일 대안은 소유 파일이 늘어 계획을 다시 세워야 했다. 보정 뒤 로컬 actionlint는 종료 0이 됐다. 재리뷰는 하지 않았고, actionlint 종료 0과 러너에서의 CI 통과로 대신하기로 기록했다.

호스트에 jq가 없었다

둘째 저장소의 보정된 계획은 러너 선행 조건을 구체 점검으로 적었다. command -v git curl python3 ruby gh sha256sum tar xz unzip bash가 모두 찾아지고 ruby -ryaml -e가 성공해야 한다는 것이다. 이 도구들은 워크플로 파일이 쓰는 실행 파일이었고, 점검은 성공했다.

그런데 PR 머리의 첫 러너 실행은 Tests 단계에서 상태줄 동작을 확인하는 시험 스크립트가 실패했다. 앞 단계는 통과했다.

jq: command not found

상태 쪽에서는 harness/verified도 실패 상태가 먼저 붙었다. 원인은 호스트에 jq가 없었다는 것이고, 선행 조건 도구 목록에도 jq가 없었다. 기록은 GitHub 호스트 러너(ubuntu-latest)는 jq를 미리 깔아 주지만 자체 호스팅 러너의 도구는 호스트가 관리한다고 적는다. 이 설명은 기록에 적힌 것이고, 내가 외부 문서로 따로 확인한 것은 아니다. 다만 GitHub 문서는 자체 호스팅 러너에서 운영체제와 다른 소프트웨어를 갱신할 책임이 사용자에게 있다고 설명한다. GitHub Docs의 Self-hosted runners 개념 문서(조회 2026-11-05)가 그렇다.

해결은 코드 수정이 아니었다. 호스트에 jq를 설치했고(호스트 쪽 별도 실행이 맡은 일이다), 같은 머리를 다시 돌렸다. 재실행(attempt 2)은 같은 러너에서 모든 단계가 success였다. 승격 점검 단계는 조건 때문에 skipped였고 harness/verified도 success가 됐다. 기록이 적은 이유는 누락된 도구가 유일한 실패 원인이라 도구를 채운 뒤 같은 후보를 다시 돌리면 충분했다는 것이다. 첫 실패 실행의 기록도 남겼다.

이 실패에서 내가 가져가는 교훈은 한 줄이다. 선행 조건 목록은 워크플로 파일이 직접 부르는 도구만으로는 모자랐고, 그 파일이 돌리는 테스트가 부르는 도구까지 포함해야 했다. 이 점검 목록 개선안은 뒤의 점검표에 권장으로 적는다.

상태 게시가 422로 거부됐다

첫째 저장소에서는 CI 자체가 아니라 상태 게시가 걸렸다. PR 머리에 harness/verified 성공을 처음 게시했을 때 종료 1, 응답 status 422였고 메시지는 이랬다.

Validation failed: Target url must use http(s) scheme

작업 그래프는 이 시도의 target_url이 로컬 파일 주소였다고 적는다. 요청 파일 자체는 기록 작성자도 열지 않았으므로, 내가 확인한 것은 응답 메시지와 작업 그래프의 서술이다. 처리는 같은 머리, 같은 컨텍스트로 target_url만 PR 주소(https)로 바꿔 다시 게시하는 것이었고, 두 번째 시도가 2026-10-17T09:44:29Z에 성공했다.

GitHub Docs의 commit statuses REST 문서(조회 2026-11-05)는 상태에 선택 항목 description과 target_url을 붙일 수 있고, target_url이 GitHub UI에서 상태의 출처로 연결되는 링크라고 설명한다. 그런데 내가 읽은 발췌에는 target_url이 http(s)여야 한다는 문장이 없었다. 그 제약은 이 글에서 422 응답 메시지로만 확인된다. 문서 전체를 다 읽은 것은 아니므로 문서에 없다고 단정하지는 않는다.

옮기기 전 저장소 상태 점검

첫째 저장소는 러너를 바꾸기 전에 저장소 상태를 읽는 단계(Phase A)를 두었고, 이 단계는 변경 없이 점검만 했다. 요구사항에는 Actions 지출 한도 0달러, 사용 중지 켜짐을 올리지 않는다는 조건이 적혀 있었다. 조건으로 적혀 있었다는 사실까지만 기록에 있고, 왜 자체 호스팅으로 옮기는지에 대한 이유는 기록되지 않았다.

  • 이미 비공개였고 gh repo edit은 실행하지 않았다. 별과 포크는 0이다.
  • develop 보호는 harness/verified와 harness/checks 필수, strict, enforce_admins, PR 필요, 승인 수 0, 강제 푸시와 삭제 금지다. main은 여기에 harness/promotion이 더해지고 PR 요구는 없다.
  • Actions는 켜짐, 허용 동작 all, SHA 고정 강제 없음, 기본 워크플로 권한 read, PR 승인 불가다. 저장소 비밀 없음, 러너 0개, 의존성 매니페스트 없음이다.
  • 비공개 저장소의 포크 PR 워크플로 실행, 쓰기 토큰, 비밀 전달이 모두 꺼져 있고 협업자는 소유자 한 명이다.
  • 비공개 상태에서 마지막 develop push 실행이 success였다.

둘째 저장소는 이 정도로 자세한 기록이 없고, 기록 범위는 같은 성격의 점검이다. 저장소는 이미 비공개였고 gh repo edit은 실행하지 않았다. 보호는 첫째와 같은 종류의 필수 체크 구성이며 규칙셋은 없었다. 그리고 비공개 상태에서도 GitHub 호스트 러너(ubuntu-24.04)로 기존 develop 실행을 다시 돌려(attempt 2, 2026-10-17T09:05:37Z부터 09:05:53Z) 모든 단계 success와 harness/promotion success를 확인했다. 러너를 바꾸기 전에 기준선이 이미 초록이었다는 뜻이라, 이후 실패를 옮긴 쪽 탓으로 좁혀 볼 수 있었다.

성공 근거

첫째 저장소의 근거는 아래 순서로 기록에 남아 있다.

  1. 로컬 점검: 내부 시험 스크립트 하나가 14개 항목 PASS로 종료 0, YAML 파싱 통과, actionlint 1.7.12 종료 0에 출력 없음, 400줄 이상 파일 없음.
  2. PR 머리 CI: 러너에서 success(2026-10-17T09:40:56Z부터 09:41:13Z). 'Set up job' 로그에 러너 이름이 보였다. 고정 도구의 체크섬 확인(actionlint 1.7.12, shellcheck v0.11.0, gitleaks 8.30.1)이 OK로 남았고, 승격 점검 단계는 PR 이벤트라 skipped였다.
  3. 병합: gh pr merge --merge, 강제 푸시 없음.
  4. 병합 뒤 develop 머리 실행도 success(09:44:48Z부터 09:45:04Z)이고 harness/promotion이 success였다.
  5. 승격은 fast-forward였다.

아래 그림은 첫째 저장소의 근거가 로컬 점검에서 승격까지 쌓인 순서를 보여 준다.

첫째 저장소의 성공 근거가 쌓인 순서를 6단계 시간순으로 보여 주는 그림이다. 첫째, 로컬 점검에서는 시험 스크립트 1개의 14개 항목이 PASS했고, YAML 파싱과 actionlint 1.7.12도 통과했으며 400줄 이상 파일은 없었다. 둘째, PR 머리 CI가 러너에서 09:40:56Z에 시작해 success였다. 셋째, 같은 실행에서 actionlint, shellcheck, gitleaks 고정 도구의 체크섬 확인이 OK로 남았고, 승격 점검 단계는 PR 이벤트라 skipped였다. 넷째, 강제 푸시 없이 gh pr merge --merge로 병합했다. 다섯째, 병합 뒤 develop 머리 실행이 09:44:48Z에 시작해 success였고 harness/promotion도 success였다. 여섯째, 승격은 fast-forward였다. 이 가운데 병합 뒤 develop 실행이 강조되어 있다.
러너 로그에 러너 이름이 찍혔다고 성공이라고 할 수는 없고, 단계별 결과에서 병합 뒤 develop 실행과 승격 점검까지 하나로 이어진 기록이 있어야 성공 근거가 된다는 것이다.

둘째 저장소는 보정 뒤 로컬 actionlint 종료 0, 재실행(attempt 2)의 러너 success, gh pr merge --merge --match-head-commit 병합, 병합 뒤 develop 점검 success로 이어졌다. 통합 리뷰는 생략했는데, 기록이 적은 근거는 워크플로 블롭이 PR 머리와 병합에서 같고 전체 스위트가 초록이라는 것이다.

러너 로그에 러너 이름이 보인다는 사실은 그 실행이 성공했다는 뜻이 아니다. 둘째 저장소의 jq 실패도 같은 러너에서 났다. 성공 근거는 단계별 결과와 병합 뒤 develop 실행, 그리고 승격 점검까지 묶어서 봐야 한다.

한계

한계는 두 기록을 합쳐 옮기되 어느 저장소 기록인지 밝힌다. 호스트, WSL, 러너 서비스 중 하나라도 꺼져 있으면 작업이 대기하고, 유료 대체는 없다는 점은 두 기록이 같다. 둘째 저장소 기록은 GitHub가 24시간 대기한 작업을 취소한다고 "공식 문서의 한도"로 적었다. 이 글을 쓰며 읽은 문서에서는 그 한도를 확인하지 못했으므로 기록의 서술로만 옮긴다. 러너 하나가 저장소의 PR과 push 작업을 모두 직렬화한다는 점은 첫째 저장소 기록에 있다.

  • 첫째 저장소 기록: WSL은 예약 작업으로 유지되며 Windows 재부팅 뒤에는 사용자 로그온이 필요하다.
  • 두 기록 공통: 작업은 sudo 없는 계정으로 돌지만 /mnt/c로 Windows 드라이브에 닿을 수 있다. 전용 배포판 분리 강화는 사용자가 거절하고 한계를 수용했다.
  • 완화책으로 기록한 것은 비공개 저장소, 단독 협업자, 포크 PR 워크플로 비활성이다(첫째 저장소 기록). 둘째 저장소 기록은 저장소가 비공개이고 포크가 없으며 트리거가 push와 pull_request뿐이라고 적는다.
  • 둘째 저장소 기록: 러너 도구는 호스트가 관리하므로 ubuntu-latest의 사전 설치 도구는 더 이상 보장되지 않는다.
  • 둘째 저장소의 부작용 한계: 라벨이 [self-hosted, Linux, X64]뿐이라, 같은 저장소에 자체 호스팅 Linux X64 러너가 더 등록되면 그쪽도 작업을 받는다.

보안 면에서는 GitHub의 보안 문서가 자체 호스팅 러너는 깨끗한 임시 VM을 보장하지 않고 신뢰할 수 없는 코드에 오래 오염될 수 있다고 경고한다. 출처는 Secure use reference(조회 2026-11-05)이며, 페이지 전문에서 해당 문장을 확인했다.

아래는 사실이 아니라 내 추정이다. 라벨을 다섯 개 쓰고 설정 파일을 두는 방식은 이 호스트에 러너가 더 늘 때 작업을 특정 러너로 좁혀 주지만, 파일 하나와 무시 규칙 대응이 따라온다. 최소 라벨은 변경이 한 줄로 끝나지만 같은 저장소에 비슷한 러너가 늘면 배정이 넓어진다. 러너 증설 계획이 없다면 최소 라벨이 간단하고, 있다면 사용자 지정 라벨이 안전하다고 보지만, 기록은 두 방식 사이의 우열을 판정하지 않았다.

옮길 때 쓸 점검표(권장)

아래는 위 기록에서 뽑은 권장 절차이고, 이번에 이 순서로 실행해 성공했다는 뜻이 아니다.

  1. 옮기기 전에 저장소 상태를 읽는다: 공개 여부, 보호 규칙과 필수 체크, Actions 설정, 포크 PR 워크플로 설정, 협업자.
  2. 현재 GitHub 호스트 러너에서 마지막 실행이 초록인지 확인해 기준선을 잡는다.
  3. 라벨 방식을 고른다. 최소 라벨이면 변경이 작고, 사용자 지정 라벨이면 actionlint 설정 파일과 무시 규칙 확인이 같이 필요하다.
  4. 워크플로 변경 뒤 로컬에서 actionlint를 돌려 라벨 거부를 먼저 본다.
  5. 선행 도구 목록에 워크플로가 직접 부르는 도구와 테스트가 쓰는 도구(이번 기록의 jq)를 모두 넣는다.
  6. 첫 러너 실행이 실패하면 원인이 호스트 쪽 누락인지 먼저 본다. 누락이면 호스트를 고친 뒤 코드를 바꾸지 않고 같은 머리를 다시 돌린다.
  7. 상태 게시의 target_url은 http(s) 주소로 보낸다.
  8. 병합 뒤 develop 머리 실행과 승격 점검까지 초록인지 본다.
  9. 호스트가 꺼진 경우의 대기를 한계로 기록해 둔다.
# 선행 조건 점검 예(권장): 워크플로가 부르는 도구 + 테스트가 쓰는 jq
command -v git curl python3 ruby gh sha256sum tar xz unzip bash jq
ruby -ryaml -e 'puts :ok'

위 명령 중 jq를 뺀 부분은 둘째 저장소 기록에서 실행해 성공한 목록이다. jq를 더한 목록 전체는 내가 권하는 형태일 뿐 실행 결과가 없다. ruby -ryaml -e 뒤의 인자 'puts :ok'도 기록이 아니라 예시로 붙인 것이다.

작성자와 검증자를 나누는 이유는 작성자와 검증자를 나누는 교차 검증 글에서 다뤘다. 이번 기록의 actionlint 거부는 그 구조에서 리뷰 모델이 막은 사례다. 필수 체크가 의도된 RED 때문에 다른 PR을 막던 문제는 의도된 RED가 다른 PR을 막는 교착을 푼 글에 있다. 다른 기록은 프로그래밍 카테고리에 모아 둔다.

AI 사용 공개

이 글이 다룬 워크플로 변경은 내가 지시한 코딩 에이전트가 작성했고, 다른 계열의 리뷰 모델이 검토했다는 것이 기록의 사실이다. 이 글의 초안 역시 AI 모델이 볼트 기록을 바탕으로 쓰고 기록과 대조했다. 이 글에 대해 사람이 따로 검수했다는 주장은 하지 않는다.

자주 묻는 질문

자체 호스팅 러너로 옮기면 runs-on만 바꾸면 되나요?

두 기록에서는 부족했다. 변경 자체는 한 줄이었지만 라벨 선택, actionlint 거부, 호스트 도구 누락(jq), 상태 게시 422가 따로 나왔다. 저장소마다 겪은 일이 달랐으니 옮기기 전에 점검표를 훑어 보는 편이 안전하다.

사용자 지정 라벨을 쓰면 actionlint가 왜 실패하나요?

actionlint는 내장 라벨만 알고, 사용자 지정 라벨은 설정 파일의 self-hosted-runner labels에 선언해야 한다. 둘째 저장소는 라벨을 줄여 해결했고, 첫째 저장소는 설정 파일을 추가했다.

러너 호스트의 도구는 어떻게 점검하나요?

호스트가 도구를 관리하므로 워크플로가 부르는 도구와 테스트가 쓰는 도구를 모두 command -v로 확인하는 것을 권한다. 둘째 저장소는 jq가 목록에 없어서 첫 실행이 실패했다.

호스트가 꺼져 있으면 작업은 어떻게 되나요?

맞는 러너가 없으면 작업이 대기한다고 두 기록이 적었다. 둘째 저장소 기록은 GitHub가 24시간 대기한 작업을 취소한다고 "공식 문서의 한도"로 적었지만, 이 글에서 그 구절은 확인하지 못했다. 두 기록 모두 유료 대체는 두지 않았다.

참고한 자료