개요

GitHub Actions는 기본적으로 GitHub에서 제공하는 hosted runner를 사용할 수 있습니다. 하지만 로컬 환경에서만 접근 가능한 리소스를 사용해야 하거나, 사설 레지스트리·로컬 Kubernetes 클러스터·내부 네트워크 환경에서 빌드와 배포를 수행해야 하는 경우에는 self-hosted runner를 구성하는 것이 유용합니다.

 

이번 글에서는 Windows 사용자 기준으로, Ubuntu WSL 개발 환경에 GitHub Actions self-hosted runner를 설치하고 서비스로 실행하는 과정을 정리합니다.

 

현재 개발 환경은 다음과 같습니다.

  • Windows에서 개발 진행
  • Ubuntu WSL을 주 개발 환경으로 사용
  • Docker는 Windows에 설치된 Docker Desktop 사용
  • GitHub Actions job은 Ubuntu WSL에 설치한 self-hosted runner에서 실행

이 구조에서는 Docker가 Windows Docker Desktop에서 실행되지만, 실제 빌드 명령은 Ubuntu WSL 환경에서 실행됩니다. 따라서 WSL 내부에서 docker 명령어를 사용할 수 있도록 Docker Desktop과 Ubuntu WSL을 연결하는 과정이 필요합니다.

Self-hosted runner 비용 관련 주의사항

Self-hosted runner를 사용할 때는 비용 정책도 함께 확인해야 합니다.

 

GitHub 공식 문서 기준으로 현재 GitHub Actions의 self-hosted runner 사용은 무료로 안내되어 있습니다. 또한 public repository에서 standard GitHub-hosted runner를 사용하는 경우도 무료로 제공됩니다. (GitHub Docs)

 

다만 GitHub는 한때 2026년 3월 1일부터 self-hosted runner 사용에 대해 분당 $0.002의 GitHub Actions cloud platform charge를 부과하겠다고 발표한 적이 있습니다. 이 발표에 따르면 public repository의 runner 사용은 계속 무료로 유지되지만, private repository에서 self-hosted runner를 사용하는 경우 과금 대상이 될 수 있었습니다. (The GitHub Blog)

 

이후 GitHub는 커뮤니티 피드백을 반영해 self-hosted GitHub Actions에 대한 과금 변경을 보류하고, 접근 방식을 재검토하겠다고 공지했습니다. 따라서 글을 작성하는 시점에는 “self-hosted runner는 무료”로 이해할 수 있지만, GitHub Actions 요금 정책은 변경될 수 있으므로 실제 운영 환경에서 사용하기 전에는 공식 billing 문서를 다시 확인하는 것이 좋습니다. (GitHub)

 

혹시 변동사항이 생긴다면 댓글로 알려주시면 감사하겠습니다.

 

정리하면 다음과 같습니다.

  • 현재 기준 self-hosted runner 사용은 무료로 안내되어 있음
  • 2026년 3월 1일부터 분당 $0.002 과금을 적용하겠다는 발표가 있었음
  • 이후 GitHub가 해당 변경을 보류하고 재검토하겠다고 공지함
  • public repository와 private repository의 과금 정책은 다를 수 있으므로 운영 전 공식 문서 확인 필요

WSL에서 Docker 사용할 수 있도록 설정

Windows에서 Docker Desktop을 사용하고 Ubuntu WSL에서 개발하는 경우, WSL 내부에서 Docker 명령어를 실행하려면 Docker Desktop의 WSL Integration을 활성화해야 합니다.

 

Docker Desktop에서 다음 경로로 이동합니다.

Settings -> Resources -> WSL Integration

기존에 설치해 둔 Ubuntu 배포판을 활성화한 뒤 Apply를 클릭합니다.

 

이 설정을 적용하면 Ubuntu WSL 터미널에서 Windows Docker Desktop의 Docker Engine을 사용할 수 있습니다. 즉, WSL 내부에서 다음과 같은 Docker 명령어를 실행할 수 있게 됩니다.

docker version

정상적으로 연결되었다면 WSL 터미널에서도 docker build, docker push 같은 명령어를 사용할 수 있습니다.

 

이 과정이 필요한 이유는 self-hosted runner가 Ubuntu WSL에서 실행되기 때문입니다. GitHub Actions workflow 안에서 Docker build를 수행하려면, runner가 실행되는 WSL 환경에서도 Docker CLI를 사용할 수 있어야 합니다.

Self-hosted runner 다운로드 및 설정

GitHub 저장소에서 self-hosted runner를 등록합니다.

 

GitHub 저장소의 다음 경로로 이동합니다.

Repository -> Settings -> Actions -> Runners -> New self-hosted runner

이후 화면에 표시되는 안내에 따라 runner를 다운로드하고 설정합니다.

 

일반적인 흐름은 다음과 같습니다.

  1. Runner 패키지 다운로드
  2. 압축 해제
  3. config.sh 실행
  4. GitHub에서 제공하는 URL과 token을 사용해 runner 등록

예시는 다음과 같습니다.

mkdir actions-runner
cd actions-runner

# GitHub 안내에 표시되는 명령어를 사용해 runner 다운로드
# 예: curl -o actions-runner-linux-x64-...tar.gz -L ...

tar xzf ./actions-runner-linux-x64-*.tar.gz

# GitHub 안내에 표시되는 URL과 token을 사용해 설정
./config.sh --url <repository-url> --token <runner-token>

실제 다운로드 URL과 token은 GitHub에서 runner를 생성할 때마다 달라질 수 있으므로, GitHub 화면에 표시되는 명령어를 그대로 사용하는 것이 좋습니다.

Self-hosted runner를 서비스로 설정하기

Self-hosted runner는 기본적으로 다음 명령어로 실행할 수 있습니다.

./run.sh

하지만 이 방식은 터미널을 열어둔 상태에서 직접 실행해야 하므로 번거롭습니다. 따라서 runner를 서비스로 등록해두면 백그라운드에서 실행할 수 있습니다.

 

먼저 runner를 다운로드하고 설정한 디렉터리로 이동합니다.

cd actions-runner

서비스를 설치합니다.

sudo ./svc.sh install

서비스를 시작합니다.

sudo ./svc.sh start

서비스 상태를 확인합니다.

sudo ./svc.sh status

정상적으로 실행 중이라면 runner가 GitHub Actions 작업을 받을 준비가 된 상태입니다.

Self-hosted runner 서비스 중지 및 제거

더 이상 runner를 사용하지 않거나 설정을 다시 구성해야 한다면 서비스를 중지하고 제거할 수 있습니다.

서비스를 중지합니다.

sudo ./svc.sh stop

서비스를 제거합니다.

sudo ./svc.sh uninstall

필요하다면 GitHub 저장소의 runner 목록에서도 해당 runner를 제거할 수 있습니다.

Repository -> Settings -> Actions -> Runners

Runner 등록 상태 확인

GitHub 저장소의 다음 경로로 이동합니다.

Repository -> Settings -> Actions -> Runners

새로 등록한 runner가 목록에 표시되는지 확인합니다.

 

Runner의 상태가 Idle 또는 Active로 표시된다면 정상적으로 등록된 것입니다. 반대로 Offline 상태라면 runner 서비스가 실행 중인지 확인해야 합니다.

sudo ./svc.sh status

GitHub Actions workflow에서 사용하기

Self-hosted runner를 사용하려면 workflow의 job에서 runs-on 값을 self-hosted runner 라벨에 맞게 지정해야 합니다.

예를 들어 다음과 같이 작성할 수 있습니다.

runs-on: [self-hosted, Linux, X64]

 

이 설정은 다음 조건을 만족하는 runner에서 해당 job을 실행하겠다는 의미입니다.

  • self-hosted 라벨을 가진 runner
  • Linux 환경의 runner
  • X64 아키텍처의 runner

예시는 다음과 같습니다.

jobs:
  build-push-and-update-overlay:
    name: Build, push, and update local overlay
    permissions:
      contents: write
    runs-on: [self-hosted, Linux, X64]
    steps:
      - name: Check out repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
        with:
          ref: ${{ github.ref_name }}
          persist-credentials: true

 

이렇게 설정하면 GitHub Actions가 해당 job을 실행할 때 GitHub-hosted runner가 아니라, 직접 등록한 self-hosted runner를 사용합니다.

정리

이번 글에서는 Windows 사용자가 Ubuntu WSL 개발 환경에서 GitHub Actions self-hosted runner를 설치하고 서비스로 실행하는 과정을 정리했습니다.

 

전체 흐름은 다음과 같습니다.

  1. Windows Docker Desktop에서 WSL Integration 활성화
  2. Ubuntu WSL에서 Docker 명령어가 동작하는지 확인
  3. GitHub 저장소에서 self-hosted runner 생성
  4. Ubuntu WSL에 runner 다운로드 및 설정
  5. svc.sh를 이용해 runner를 서비스로 등록
  6. GitHub Actions workflow의 runs-on에 self-hosted runner 라벨 지정

Self-hosted runner를 사용하면 로컬 네트워크, 사설 Docker Registry, 로컬 Kubernetes 클러스터처럼 GitHub-hosted runner에서 접근하기 어려운 리소스를 활용할 수 있습니다.

 

다만 self-hosted runner는 사용자의 로컬 머신 또는 서버에서 직접 명령을 실행하므로 보안에 주의해야 합니다. 특히 public repository에서 외부 PR이 self-hosted runner에서 실행되지 않도록 workflow trigger와 권한 설정을 신중하게 관리하는 것이 좋습니다.

Reference

  • GitHub Docs - Adding self-hosted runners
  • GitHub Docs - Configuring the self-hosted runner application as a service
  • GitHub Docs - GitHub Actions billing
  • GitHub Blog - GitHub Actions pricing changes

'Devops > GitHub Actions' 카테고리의 다른 글

GitHub Actions에서 커밋 해시 기반 Docker 이미지 태그로 배포 자동화하기  (0) 2026.05.29

티스토리툴바