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

어느 순간부터 GitHub Actions 에서 패키지 설치가 들어간 Job 만 계속 실패했습니다. 빌드도 테스트도 아니고 install 단계에서만 멈춥니다.

받아 오는 패키지 중에 공용 레지스트리에 못 올리는 코드가 섞여 있습니다. 그래서 Nexus 를 사설 npm 레지스트리로 띄워 두고 각 프로젝트의 .npmrc 가 그 주소를 보게 해 뒀고, 이 Nexus 는 내부망 안에서만 열려 있습니다.

CI 쪽은 runs-on 을 따로 지정하지 않아서 GitHub 이 관리하는 러너가 잡힙니다. 워크플로가 돌 때마다 새로 뜨는 일회용 머신이고, 거기서 체크아웃하고 설치·빌드·테스트를 돌립니다.

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

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

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 가 써야 한다면, 러너를 그 망 안에 두는 게 출발점입니다. 호스티드 러너는 편하지만 “외부에서 돈다” 는 전제를 항상 깔고 갑니다.