나의 macOS를 GitHub Actions Runner로 만들기

1. Introduce

Private 레포에서 GitHub Actions를 사용하다 보면, 실행 시간이 무한하지 않다는 사실을 자연스럽게 체감하게 된다. 초기에는 단순한 빌드와 테스트만 수행했기 때문에 큰 문제가 되지 않았지만, 워크플로우가 늘어나고 CI 시간이 길어지면서 상황은 점점 달라졌다.

 

PR 단위로 여러 워크플로우가 동시에 실행되고, 테스트 시간이 길어질수록 사용량은 빠르게 증가하였다. 이러한 흐름이 반복되다 보니, CI 실행 자체가 부담으로 느껴지기 시작했다. 그리고 자연스럽게 한 가지 질문에 도달했다.

 

GitHub Actions를 꼭 GitHub에서만 실행해야 할까?

 

GitHub Actions를 사용하고 있다는 이유만으로, 실행 환경까지 GitHub의 인프라에 종속될 필요는 없다. 실제로 GitHub는 사용자가 직접 실행 환경을 구성하고, 해당 환경에서 워크플로우를 실행할 수 있는 방법을 제공하고 있다.

 

이 글에서는 GitHub-hosted runner 대신, 나의 macOS로 GitHub Actions를 실행하는 Runner를 구축해 본 경험을 정리해보고자 한다.

 

관련 모든 코드는 아래 레포에서 확인할 수 있습니다.

GitHub - WooJJam/self-hosted-runner-playground

 

---

 

2. About Github-hosted Runner

GitHub hosted runner

 

GitHub Actions가 트리거되어 runner가 실행되는 과정은 어렵지 않다.

1. 개발자가 이벤트를 발생시킨다. (`git push`, `pull_request`, `workflow_dispatch`)
2. GitHub Actions가 이벤트를 감지하고, 워크플로우를 트리거한다.
3. 워크플로우가 로드되고, 정의된 job 목록이 확정된다.
4. 각 job에 대해 실행 환경(runs-on)을 기준으로 runner를 매칭한다.
5. GitHub가 job마다 별도의 GitHub-hosted runner 인스턴스를 할당한다.

GitHub Actions에서 가장 기본이 되는 실행 환경은 `GitHub-hosted runner`다. GitHub에 이벤트가 발생해 GitHub Actions가 트리거되면, GitHub는 내부적으로 관리하고 있는 runner 중 하나를 할당해 각 job을 실행한다.

 

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello from GitHub-hosted runner!"

사용자는 runner를 직접 생성하거나 관리할 필요 없이, 단순히 `runs-on` 옵션을 통해 필요한 실행 환경(`ubuntu-latest`)만 지정하면 된다. 그러면 GitHub가 해당 환경의 runner를 할당해 job을 실행해준다. 정리하면 GitHub는 job을 실행하기 위한 runner를 기본적으로 제공하는데, 그것이 `GitHub-hosted runner` 인 것이다.

 

---

 

3. About Self-hosted Runner

GitHub 공식 문서 에서도 언급하듯이, Guthub Actions는 사용자가 직접 runner를 호스팅할 수 있는 방식도 제공한다. 이것이 `Self-hosted runner` 이다. `Self-hosted runner`는 로컬 머신이나 사내 서버와 같이, 사용자가 직접 관리하는 환경을 GitHub Actions의 실행 환경으로 사용하는 방식이다.

 

설정 방식은 GitHub Ations 공식 문서 를 참고하면 쉽게 설정할 수 있다.

name: Test Self-hosted Runner

on:
  workflow_dispatch:

jobs:
  test:
    runs-on: wojjam-macos-runner
    steps:
      - run: echo "Hello from Self-hosted runner!"

나는 `woojjam-macos-runner` 의 이름으로 새로운 runner를 생성하였다.

다음과 같이 `runs-on` 에 직접 설정한 runner를 지정해주면, GitHub는 `GitHub-hosted runner` 를 사용하지 않고, 사용자가 등록한 runner 중 하나를 찾아 job을 실행한다. Workflow와 job의 실행 방식은 완전 동일하지만, 실행되는 환경만 달라지는 것이다.

 

실행 결과

실행 결과를 확인하면 `GitHub-hosted runner`가 아닌 나의 macOS에서 workflow가 정상적으로 실행된 것을 확인할 수 있다.