GitHub Actions 러너는 무엇이고 어떻게 고를까?

GitHub Actions 러너는 워크플로라는 작업 지시서를 받아 실제로 일하는 컴퓨터입니다. 코드를 올리면 "테스트를 돌리고, 빌드하고, 서버에 배포하라"는 지시서가 실행되는데, 그 명령을 하나하나 수행하는 기계가 러너입니다. GitHub가 만든 러너 프로그램(actions/runner)이 이 컴퓨터 안에서 작업을 받아 처리합니다.

예전에는 이런 자동화를 하려면 Jenkins 같은 서버를 직접 세우고 관리해야 했습니다. GitHub Actions는 워크플로 파일에 runs-on: ubuntu-latest 한 줄만 쓰면 GitHub가 컴퓨터를 빌려주고, 필요하면 내 서버를 러너로 등록해 쓸 수도 있게 했습니다. 이 글에서는 두 종류의 러너가 어떻게 다른지, 내 서버를 러너로 등록하는 방법, 그리고 상황별로 어떤 러너를 고르면 되는지 정리합니다.

핵심 요약

• 러너는 GitHub Actions 워크플로의 각 작업(job)을 실제로 실행하는 컴퓨터이고, runs-on으로 어떤 러너에서 돌릴지 정합니다.
• GitHub 호스티드 러너는 작업마다 새 가상 컴퓨터를 빌려주고 끝나면 버리며, 공개 저장소에서는 무료입니다.
• 셀프 호스티드 러너는 내 서버를 등록해 쓰는 방식으로 사양과 내부망을 마음대로 쓰지만, 관리와 보안 책임이 내게 있어 공개 저장소에는 쓰지 않는 것이 원칙입니다.

워크플로는 지시서이고, 러너가 그 지시서를 실행합니다

GitHub Actions의 설정은 저장소의 .github/workflows/ 폴더에 들어가는 YAML 파일입니다. 이 파일에는 언제 실행할지(on), 어떤 작업을 할지(jobs), 각 작업의 단계(steps)가 적혀 있습니다.

name: test
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest   # 어느 러너에서 실행할지
    steps:
      - uses: actions/checkout@v5
      - run: npm ci
      - run: npm test

여기서 runs-on이 러너를 고르는 줄입니다. 코드가 올라오면 GitHub는 ubuntu-latest라는 이름표(label)에 맞는 러너를 찾아 작업을 넘기고, 러너는 저장소를 내려받아 npm ci와 npm test를 차례로 실행한 뒤 결과를 GitHub에 돌려보냅니다. 작업(job) 하나는 러너 하나에서 실행되고, 작업이 여러 개면 여러 러너에서 동시에 돌 수 있습니다.

러너는 빌려 쓰거나, 내 컴퓨터를 등록합니다

그림 1

GitHub 호스티드 러너는 GitHub가 준비해 둔 컴퓨터입니다. 작업이 시작될 때마다 새 가상 컴퓨터(VM)가 만들어지고, 작업이 끝나면 버려집니다. 그래서 이전 작업의 흔적이 남지 않고 관리할 것도 없습니다. Linux와 macOS에서는 비밀번호 없는 sudo, Windows에서는 관리자 권한이 주어져 필요한 프로그램을 자유롭게 설치할 수 있습니다.

기본 사양은 저장소 종류에 따라 다릅니다. 2026년 10월 기준 공식 문서에 따르면 Linux·Windows 기본 러너는 공개 저장소에서 CPU 4개·메모리 16GB, 비공개 저장소에서 CPU 2개·메모리 8GB이고, 저장 공간은 14GB입니다. 가벼운 작업용으로는 CPU 1개짜리 ubuntu-slim도 있습니다.

셀프 호스티드 러너는 내가 가진 컴퓨터에 러너 프로그램을 설치해 GitHub에 등록하는 방식입니다. 사무실 서버, 클라우드 VM, 집의 남는 PC 모두 러너가 될 수 있습니다. 원하는 만큼 큰 사양을 쓰고, 사내망의 DB나 GPU, 미리 받아 둔 캐시를 그대로 활용할 수 있다는 것이 장점입니다. 대신 운영체제와 프로그램 업데이트는 직접 해야 하고, 작업마다 깨끗한 환경이 보장되지 않습니다.

내 서버를 러너로 등록하는 방법은 세 단계입니다

셀프 호스티드 러너 등록은 생각보다 간단합니다. 저장소의 Settings → Actions → Runners → New self-hosted runner로 들어가 운영체제를 고르면, GitHub가 그 서버에서 실행할 명령을 보여 줍니다. Linux 기준 흐름은 다음과 같습니다.

# 1) 러너 프로그램 내려받기 (화면에 나온 최신 버전 주소를 그대로 사용)
mkdir actions-runner && cd actions-runner
curl -o actions-runner.tar.gz -L <화면에 나온 다운로드 주소>
tar xzf actions-runner.tar.gz

# 2) 저장소에 등록 (토큰은 화면에서 발급, 1시간 뒤 만료)
./config.sh --url https://github.com/<소유자>/<저장소> --token <등록 토큰>

# 3) 서비스로 설치해 재부팅 후에도 계속 대기
sudo ./svc.sh install
sudo ./svc.sh start

등록이 끝나면 터미널에 "Connected to GitHub", "Listening for Jobs"가 표시되고, 러너 목록에 초록색 Idle 상태로 나타납니다. 러너는 GitHub 쪽으로 나가는 HTTPS(443번 포트) 연결만 있으면 동작하므로, 공유기나 방화벽에서 외부 접속 포트를 열 필요가 없습니다.

워크플로에서는 runs-on에 self-hosted 이름표를 쓰면 이 러너로 작업이 갑니다. 러너에는 self-hosted, 운영체제, CPU 종류 같은 이름표가 자동으로 붙고, gpu처럼 직접 이름표를 더해 특정 러너를 고를 수도 있습니다.

jobs:
  deploy:
    runs-on: [self-hosted, linux]
    steps:
      - uses: actions/checkout@v5
      - run: ./deploy.sh   # 사내망 서버에 바로 배포

공개 저장소에는 셀프 호스티드 러너를 쓰지 않습니다

GitHub 보안 가이드는 셀프 호스티드 러너를 공개 저장소에는 거의 쓰지 말라고 분명히 적고 있습니다. 공개 저장소에는 누구나 풀 리퀘스트(PR)를 보낼 수 있고, 그 PR에 들어 있는 코드가 내 서버에서 실행될 수 있기 때문입니다.

호스티드 러너는 작업이 끝나면 VM을 버리지만, 셀프 호스티드 러너는 같은 컴퓨터가 계속 쓰입니다. 악성 코드가 한 번 실행되면 다음 작업까지 살아남아 비밀값이나 GITHUB_TOKEN을 훔치거나, 같은 망의 다른 서버로 번질 수 있습니다. 비공개 저장소라도 저장소를 포크해 PR을 보낼 수 있는 사람이 있다면 같은 위험이 있습니다.

위험을 줄이는 방법은 러너를 작업 하나만 처리하고 사라지게 만드는 것입니다. GitHub는 REST API로 작업 하나만 실행하고 자동으로 제거되는 일회용(JIT) 러너를 만들 수 있게 하고, 아예 러너 전용 머신이나 VM을 따로 두는 것도 좋은 방법입니다.

대부분은 호스티드 러너로 시작하면 됩니다

그림 2

어떤 러너를 고를지는 몇 가지 질문으로 정리됩니다. 공개 저장소라면 무료이고 안전한 호스티드 러너가 정답입니다. 사내망 DB나 장비, GPU가 꼭 필요하다면 비공개 저장소에서 셀프 호스티드 러너를 씁니다.

빌드가 느리거나 사용량이 많다면 GitHub가 제공하는 더 큰 사양의 호스티드 러너와 셀프 호스티드 러너의 비용을 비교합니다. 작업이 하루 수백 개씩 몰리는 팀이라면 ARC(Actions Runner Controller)가 있습니다. Kubernetes 위에서 작업량에 맞춰 일회용 러너를 자동으로 늘리고 줄이는 GitHub 공식 도구입니다.

요금도 고려해야 합니다. 공개 저장소의 기본 호스티드 러너는 무료이고, 비공개 저장소는 요금제별 무료 분량을 쓴 뒤 분 단위로 과금됩니다. GitHub는 2026년 1월 1일부터 호스티드 러너 요금을 최대 39% 내렸습니다. 셀프 호스티드 러너에 분당 0.002달러를 받겠다는 계획도 2025년 12월에 발표했다가, 이후 시행을 보류하고 방식을 다시 검토하겠다고 공지했습니다.

구분	GitHub 호스티드 러너	셀프 호스티드 러너
실행 환경	작업마다 새 VM, 끝나면 폐기	내 서버·VM, 환경이 계속 남음
관리	GitHub가 관리	OS·프로그램 업데이트를 직접
사양	정해진 사양 (큰 러너는 유료)	원하는 사양, GPU·내부망 사용 가능
비용	공개 저장소 무료, 비공개는 무료 분량 후 과금	러너 프로그램은 무료, 서버 비용은 직접 부담
보안	작업 간 격리가 기본	공개 저장소에는 쓰지 않음, 일회용 러너 권장

정리하며

GitHub Actions 러너는 워크플로의 각 작업을 실제로 실행하는 컴퓨터이고, runs-on 한 줄로 GitHub의 컴퓨터를 빌릴지 내 서버를 쓸지 정합니다. 호스티드 러너는 매번 깨끗한 환경을 공짜 또는 적은 비용으로 주고, 셀프 호스티드 러너는 사양과 내부망을 자유롭게 쓰는 대신 관리와 보안을 내가 책임집니다.

처음이라면 호스티드 러너로 시작하고, 사내망 배포나 GPU처럼 꼭 필요한 이유가 생길 때 비공개 저장소에서 셀프 호스티드 러너를 더하는 것이 안전합니다. 이때 러너를 전용 머신에 두고, 가능하면 작업 하나만 처리하고 사라지는 일회용 러너로 운영하는 것을 권합니다.

원본: GitHub Actions Runner · GitHub · MIT 라이선스 · github.com/actions/runner (2026년 10월 26일 v2.338.2). ARC는 Apache-2.0 라이선스로 github.com/actions/actions-runner-controller에 공개되어 있습니다. 사양·보안 권장·요금은 2026년 10월 28일 기준 GitHub 공식 문서와 변경 공지를 바탕으로 정리했습니다.

한마디로 정리하면

GitHub Actions 러너는 주방에서 레시피대로 요리하는 요리사와 같습니다. 워크플로는 "재료를 씻고, 굽고, 담아라"라고 적힌 레시피이고, 러너는 그 레시피를 받아 실제로 요리하는 사람입니다.

호스티드 러너는 출장 요리사입니다. 부를 때마다 깨끗한 도구를 들고 와서 요리하고, 끝나면 뒷정리까지 해서 돌아갑니다. 셀프 호스티드 러너는 우리 집 전속 요리사입니다. 집의 큰 오븐과 냉장고 재료를 마음껏 쓸 수 있지만, 주방 관리는 내 몫이고 아무나 레시피를 들고 와서 시키게 두면 곤란해집니다.

대부분의 요리는 출장 요리사로 충분하고, 우리 집에서만 할 수 있는 요리가 생길 때 전속 요리사를 두면 됩니다.