호스티드 러너에서 내부 npm 레지스트리 접근 불가 — self-hosted 러너

비공개 패키지를 사설 npm 레지스트리(Nexus)로 받는 프로젝트들이 있습니다. CI 를 GitHub Actions 로 돌리는데, 어느 순간부터 패키지 설치가 들어간 Job 만 계속 실패했습니다. 빌드도 테스트도 아니고 install 단계에서 멈춥니다.

증상 — 내부 레지스트리로 가는 요청이 타임아웃

로그는 이렇게 끝났습니다.

ERR_PNPM_META_FETCH_FAIL
GET https://<내부-레지스트리>/repository/npm-group/... failed,
reason: Socket timeout

install 이 포함된 Job 은 전부 이 패턴으로 timeout 이고, 그 외 Job 은 멀쩡합니다.

원인 — 내부망 밖의 호스티드 러너

이 내부 레지스트리는 내부망에서만 접근할 수 있게 막혀 있습니다. 그리고 GitHub Actions 의 기본 러너(GitHub-hosted runner)는 GitHub 인프라, 즉 외부 네트워크에서 실행됩니다. 외부 IP 라 내부망 전용 주소로는 소켓 연결 자체가 성립하지 않습니다. 방화벽에서 막히는 것도 아니고, 애초에 경로가 없어서 timeout 으로만 끝납니다.

빌드·테스트가 멀쩡했던 건 그것들이 외부(공용 레지스트리·소스)만 건드렸기 때문이고, 내부 레지스트리를 처음 부르는 install 만 벽에 부딪힌 겁니다.

해결 — 러너를 내부망 안으로

그 Job 을 self-hosted 러너로 옮겼습니다. self-hosted 러너는 내부망 안(예: 사설망 VM 이나 쿠버네티스)에서 돌기 때문에, 내부 레지스트리에 정상적으로 닿습니다.

jobs:
  build:
    runs-on: self-hosted   # GitHub-hosted → 내부망 self-hosted

러너 수요가 많으면 Actions Runner Controller(ARC)로 내부망 쿠버네티스 위에 러너를 필요할 때만 띄우는 방법도 있습니다. 핵심은 같습니다 — 러너가 그 내부망 안에 있어야 한다.

자격증명보다 먼저 — 러너의 네트워크 위치

“CI 에서 X 를 못 받는다” 는 문제는 자격증명이나 레지스트리 설정 문제처럼 보이기 쉽지만, 먼저 러너가 그 대상에 네트워크로 닿을 수 있는 위치인지를 봐야 합니다. 내부망 전용 리소스(레지스트리·DB·내부 API)를 CI 가 써야 한다면, 러너를 그 망 안에 두는 게 출발점입니다. 호스티드 러너는 편하지만 “외부에서 돈다” 는 전제를 항상 깔고 있습니다.