셀프 호스팅 러너 참조

셀프 호스팅 러너 참조

셀프 호스팅 러너를 설정하고 사용하는 방법에 대한 정보를 알려드릴게요. 직접 관리하는 머신에서 워크플로를 돌리고 싶을 때 활용하세요.

출처: 문서

본문

셀프 호스팅 러너를 설정하고 사용하는 방법에 대한 정보를 확인할 수 있습니다.

셀프 호스팅 러너 머신 요구 사항

다음 요구 사항을 충족하는 머신은 셀프 호스팅 러너로 사용할 수 있습니다:

  • 머신에 셀프 호스팅 러너 애플리케이션을 설치하고 실행할 수 있어야 합니다. Supported operating systems와 Supported processor architectures를 참고하세요.
  • 머신이 GitHub Actions와 통신할 수 있어야 합니다.
  • 머신이 실행하려는 워크플로 유형에 충분한 하드웨어 리소스를 가져야 합니다. 셀프 호스팅 러너 애플리케이션 자체는 최소한의 리소스만 요구합니다.
  • Docker 컨테이너 액션이나 서비스 컨테이너를 사용하는 워크플로를 실행하려면 Linux 머신을 사용하고 Docker가 설치되어 있어야 합니다.

지원되는 운영 체제

Linux
  • Red Hat Enterprise Linux 8 이상
  • CentOS 8 이상
  • Oracle Linux 8 이상
  • Fedora 29 이상
  • Debian 10 이상
  • Ubuntu 20.04 이상
  • Linux Mint 20 이상
  • openSUSE 15.2 이상
  • SUSE Enterprise Linux (SLES) 15 SP2 이상
Windows
  • Windows 10 64비트
  • Windows 11 64비트
  • Windows Server 2016 64비트
  • Windows Server 2019 64비트
  • Windows Server 2022 64비트
macOS
  • macOS 11.0 (Big Sur) 이상

지원되는 프로세서 아키텍처

  • x64 - Linux, macOS, Windows.
  • ARM64 - Linux, macOS, Windows (현재 공개 미리보기).
  • ARM32 - Linux.

셀프 호스팅 러너의 라우팅 우선순위

잡을 셀프 호스팅 러너로 라우팅할 때 GitHub는 잡의 runs-on 라벨과 그룹과 일치하는 러너를 찾습니다:

  • GitHub가 잡의 runs-on 라벨과 그룹과 일치하는 온라인이고 유휴(idle)한 러너를 찾으면 잡이 할당되어 러너로 전송됩니다.
    • 러너가 60초 이내에 할당된 잡을 받지 않으면 잡이 다시 대기열에 배치되어 새 러너가 받을 수 있게 됩니다.
  • GitHub가 잡의 runs-on 라벨과 그룹과 일치하는 온라인이고 유휴한 러너를 찾지 못하면, 러너가 온라인 상태가 될 때까지 잡은 대기열에 남아 있습니다.
  • 잡이 24시간 이상 대기열에 남아 있으면 잡은 실패합니다.

자동 확장(Autoscaling)

자동 확장을 사용하면 수요에 따라 셀프 호스팅 러너 수를 동적으로 조정할 수 있습니다. 이는 리소스 활용을 최적화하고 피크 시간에 충분한 러너 용량을 보장하며 활동이 적은 기간에는 비용을 줄여줍니다. 셀프 호스팅 러너에 대한 자동 확장을 구현하는 방법은 여러 가지가 있으며, 각각 복잡성, 신뢰성, 응답성 측면에서 서로 다른 트레이드오프가 있습니다.

Actions Runner Controller

GitHub 호스팅 러너는 필요에 따라 본질적으로 자동 확장됩니다. GitHub 호스팅 러너는 자동 확장 솔루션을 개발하거나 구현하는 것에 대한 저유지 관리·비용 효율적인 대안이 될 수 있습니다. 자세한 내용은 GitHub-hosted runners를 참고하세요.

Actions Runner Controller(ARC)는 GitHub 스케일 세트 API의 참조 구현이며, 셀프 호스팅 러너 자동 확장을 위한 권장 Kubernetes 기반 솔루션입니다. ARC는 Kubernetes 환경에서 GitHub Actions를 실행하는 팀을 위한 완전하고 프로덕션 지원 가능한 자동 확장 솔루션을 제공합니다.

GitHub는 Kubernetes 인프라가 있고 Kubernetes 전문성이 있는 팀에 ARC를 권장합니다. ARC는 프로비저닝부터 잡 실행, 정리까지 클러스터 내에서 러너의 전체 수명 주기를 처리합니다.

자세한 내용은 Actions Runner Controller와 Support for Actions Runner Controller를 참고하세요.

GitHub Actions Runner Scale Set Client

GitHub Actions Runner Scale Set Client는 플랫폼 팀, 통합업체, 인프라 제공자가 VM, 컨테이너, 온프레미스 인프라, 클라우드 서비스 전반에서 GitHub Actions 러너용 맞춤형 자동 확장 솔루션을 만들 수 있게 해주는 독립형 Go 기반 모듈이며, Windows, Linux, macOS 플랫폼을 지원합니다.

이 클라이언트는 스케일 세트에 대한 GitHub API 상호 작용을 오케스트레이션하고 인프라 프로비저닝은 사용자가 담당합니다. 러너가 어떻게 생성·확장·파괴되는지 정의하고 여러 라벨로 러너를 구성해서 유연한 잡 라우팅과 타게팅을 할 수 있습니다. 이를 통해 조직은 러너 수명 주기 관리에 대한 세밀한 제어와 잡 실행에 대한 실시간 텔레메트리를 얻을 수 있습니다.

이 클라이언트는 기본 구성으로 바로 작동하도록 설계되어 팀이 빠르게 자동 확장을 구현할 수 있습니다. 그러나 진정한 강점은 유연성에 있습니다—클라이언트는 각 조직의 특정 인프라 요구 사항, 규정 준수 제약, 운영 워크플로를 충족하도록 확장·사용자 지정하도록 만들어졌습니다. 단순한 확장 로직이 필요하든 복잡한 다중 환경 프로비저닝 전략이 필요하든 클라이언트는 필요에 맞게 적응합니다.

GitHub Actions Runner Scale Set Client는 오픈 소스 프로젝트입니다. actions/scaleset 저장소에는 시작하는 데 도움이 되는 완전한 소스 코드, 포괄적인 문서, 실용적인 예시가 포함되어 있습니다. 다양한 인프라 시나리오에 대한 구현 가이드, 샘플 구성, 다른 프로비저닝 시스템과 클라이언트를 통합하는 방법을 보여주는 참조 아키텍처를 찾을 수 있습니다. 이 저장소에는 클라이언트를 확장하거나 자동 확장 패턴을 커뮤니티와 공유하는 데 관심이 있는 팀을 위한 기여 지침도 포함되어 있습니다.

참고: Runner Scale Set Client는 Actions Runner Controller(ARC)를 대체하지 않습니다. ARC는 스케일 세트 API의 참조 구현이자 러너 자동 확장을 위한 권장 Kubernetes 솔루션으로 남아 있습니다. 대신 클라이언트는 Kubernetes 밖에서 맞춤형 자동 확장 솔루션을 구축하기 위해 동일한 스케일 세트 API와 인터페이스하는 보완 도구입니다.

자동 확장용 임시 러너(Ephemeral runners)

GitHub는 임시 셀프 호스팅 러너로 자동 확장을 구현할 것을 권장합니다. 영구(persistent) 셀프 호스팅 러너로 자동 확장하는 것은 권장하지 않습니다. 특정 경우에 GitHub는 잡이 종료되는 동안 영구 러너에 할당되지 않는다는 것을 보장할 수 없습니다. 임시 러너를 사용하면 GitHub가 러너에 잡을 하나만 할당하므로 이를 보장할 수 있습니다.

이 접근 방식은 자동화를 사용해서 각 잡에 깨끗한 환경을 제공할 수 있으므로 러너를 임시 시스템으로 관리할 수 있게 해줍니다. 이는 이전 잡의 민감한 리소스 노출을 제한하고, 손상된 러너가 새 잡을 받는 위험을 완화하는 데도 도움이 됩니다.

[!WARNING] 임시 러너의 러너 애플리케이션 로그 파일은 문제 해결과 진단 목적으로 외부 로그 저장 솔루션으로 전달되어야 합니다. 임시 러너가 배포되는 데 필수는 아니지만, GitHub는 프로덕션 환경에 임시 러너 자동 확장 솔루션을 배포하기 전에 러너 로그가 외부로 전달·보존되도록 보장할 것을 권장합니다. 자세한 내용은 Monitoring and troubleshooting self-hosted runners를 참고하세요.

환경에 임시 러너를 추가하려면 config.sh로 러너를 등록할 때 --ephemeral 파라미터를 포함하세요. 예를 들어:

./config.sh --url https://github.com/octo-org --token example-token --ephemeral

GitHub Actions 서비스는 러너가 하나의 잡을 처리한 후 자동으로 러너 등록을 해제합니다. 그런 다음 러너가 등록 해제된 후 러너를 정리하는 자체 자동화를 만들 수 있습니다.

[!NOTE] 잡이 특정 유형의 러너에 대해 라벨이 지정되었지만 해당 유형과 일치하는 러너가 없으면 잡은 대기열에 배치될 때 즉시 실패하지 않습니다. 대신 24시간 타임아웃 기간이 만료될 때까지 잡은 대기열에 남아 있습니다.

또는 REST API를 사용해서 임시 just-in-time 러너를 만들 수 있습니다. 자세한 내용은 REST API endpoints for self-hosted runners를 참고하세요.

셀프 호스팅 러너의 러너 소프트웨어 업데이트

기본적으로 셀프 호스팅 러너는 새 버전의 러너 소프트웨어가 나올 때마다 자동으로 소프트웨어 업데이트를 수행합니다. 컨테이너에서 임시 러너를 사용한다면 이로 인해 새 러너 버전이 릴리스될 때 반복적인 소프트웨어 업데이트가 발생할 수 있습니다. 자동 업데이트를 끄면 자신의 일정에 맞춰 컨테이너 이미지의 러너 버전을 직접 업데이트할 수 있습니다.

자동 소프트웨어 업데이트를 끄고 직접 소프트웨어 업데이트를 설치하려면 config.sh로 러너를 등록할 때 --disableupdate 플래그를 지정하세요. 예를 들어:

./config.sh --url https://github.com/YOUR-ORGANIZATION --token EXAMPLE-TOKEN --disableupdate

자동 업데이트를 비활성화하면 여전히 러너 버전을 정기적으로 업데이트해야 합니다. GitHub Actions의 새 기능에는 GitHub Actions 서비스 와 러너 소프트웨어 양쪽의 변경이 필요합니다. 소프트웨어 업데이트 없이 러너가 GitHub Actions의 새 기능을 활용하는 잡을 올바르게 처리하지 못할 수 있습니다.

자동 업데이트를 비활성화하면 새 버전이 제공된 후 30일 이내에 러너 버전을 업데이트해야 합니다. actions/runner 저장소에서 릴리스 알림을 구독하는 것이 좋습니다. 자세한 내용은 Configuring notifications를 참고하세요.

최신 러너 버전을 설치하는 방법에 대한 지침은 최신 릴리스의 설치 지침을 참고하세요.

[!WARNING] 메이저, 마이너, 패치 릴리스를 포함한 소프트웨어의 모든 업데이트는 사용 가능한 업데이트로 간주됩니다. 30일 이내에 소프트웨어 업데이트를 수행하지 않으면 GitHub Actions 서비스는 러너에 잡을 대기열에 배치하지 않습니다. 또한 중요한 보안 업데이트가 필요한 경우 GitHub Actions 서비스는 러너가 업데이트될 때까지 잡을 대기열에 배치하지 않습니다.

자동 확장용 웹훅

workflow_job 웹훅에서 받은 페이로드를 사용해서 자체 자동 확장 환경을 만들 수 있습니다. 이 웹훅은 저장소, 조직, 엔터프라이즈 레벨에서 사용할 수 있으며, 이 이벤트의 페이로드에는 워크플로 잡 수명 주기의 단계에 해당하는 action 키가 포함됩니다(예: 잡이 queued, in_progress, completed일 때). 그런 다음 이러한 웹훅 페이로드에 응답해서 자체 확장 자동화를 만들어야 합니다.

참고: 이 접근 방식은 확장 결정을 내리기 위해 웹훅 전달의 적시성에 의존하므로 지연과 신뢰성 문제가 발생할 수 있습니다. 대용량 자동 확장 시나리오에서는 Actions Controller나 Scale Set Client를 사용하는 것을 고려하세요.

인증 요구 사항

API를 사용해서 저장소 및 조직 셀프 호스팅 러너를 등록하고 삭제할 수 있습니다. API에 인증하려면 자동 확장 구현이 액세스 토큰이나 GitHub 앱을 사용할 수 있습니다.

액세스 토큰에는 다음 스코프가 필요합니다:

  • 비공개 저장소의 경우 repo 스코프가 있는 액세스 토큰을 사용하세요.
  • 공개 저장소의 경우 public_repo 스코프가 있는 액세스 토큰을 사용하세요.
  • 조직의 경우 admin:org 스코프가 있는 액세스 토큰을 사용하세요.

GitHub App으로 인증하려면 다음 권한이 할당되어야 합니다:

  • 저장소의 경우 administration 권한을 할당하세요.
  • 조직의 경우 organization_self_hosted_runners 권한을 할당하세요.

API를 사용해서 엔터프라이즈 셀프 호스팅 러너를 등록하고 삭제할 수 있습니다. API에 인증하려면 자동 확장 구현이 액세스 토큰을 사용할 수 있습니다.

액세스 토큰에는 manage_runners:enterprise 스코프가 필요합니다.

통신

셀프 호스팅 러너는 잡 할당을 받고 러너 애플리케이션의 새 버전을 다운로드하기 위해 GitHub에 연결합니다.

GitHub Actions 러너 애플리케이션은 오픈 소스입니다. runner 저장소에서 기여하고 이슈를 제기할 수 있습니다. 새 버전이 릴리스되면 러너 애플리케이션은 잡이 러너에 할당될 때, 또는 잡이 할당되지 않은 경우 릴리스 후 1주일 이내에 자동으로 업데이트됩니다.

GitHub와의 통신 요구 사항

  • 셀프 호스팅 러너 애플리케이션은 GitHub Actions 잡을 받아 실행하려면 호스트 머신에서 실행 중이어야 합니다.
  • 호스트 머신은 초당 최소 70킬로비트의 업로드·다운로드 속도로 적절한 네트워크 접근 권한을 가져야 합니다.
  • 호스트 머신은 포트 443에서 아웃바운드 HTTPS 연결을 만들 수 있어야 합니다.
  • 셀프 호스팅 러너에 할당된 워크플로의 기능에 따라 호스트 머신은 아래 나열된 GitHub 도메인과 통신할 수 있어야 합니다.

기능별 접근 가능한 도메인

[!NOTE] 나열된 도메인 중 일부는 CNAME 레코드로 구성됩니다. 일부 방화벽은 모든 CNAME 레코드에 대해 재귀적으로 규칙을 추가해야 할 수 있습니다. CNAME 레코드는 나중에 변경될 수 있으며 나열된 도메인만 일정하게 유지된다는 점에 유의하세요.

필수 작업에 필요:

github.com
api.github.com
*.actions.githubusercontent.com

액션 다운로드에 필요:

codeload.github.com

잡 요약, 로그, 워크플로 아티팩트, 캐시 업로드/다운로드에 필요:

results-receiver.actions.githubusercontent.com
*.blob.core.windows.net

러너 버전 업데이트에 필요:

objects.githubusercontent.com
objects-origin.githubusercontent.com
github-releases.githubusercontent.com
github-registry-files.githubusercontent.com

OIDC 토큰 가져오기에 필요:

*.actions.githubusercontent.com

GitHub Packages에 패키지나 컨테이너를 다운로드하거나 게시하는 데 필요:

*.pkg.github.com
pkg-containers.githubusercontent.com
ghcr.io

Git Large File Storage에 필요

github-cloud.githubusercontent.com
github-cloud.s3.amazonaws.com

Dependabot 업데이트 잡에 필요

dependabot-actions.githubapp.com

릴리스 자산 다운로드에 필요:

release-assets.githubusercontent.com

VNet에 필요:

api.snapcraft.io
*.core.windows.net

또한 워크플로는 다른 네트워크 리소스에 접근해야 할 수 있습니다.

GitHub 조직이나 엔터프라이즈 계정에 IP 주소 허용 목록을 사용한다면 셀프 호스팅 러너의 IP 주소를 허용 목록에 추가해야 합니다. GitHub Enterprise Cloud 문서의 Managing allowed IP addresses for your organization 또는 Enforcing policies for security settings in your enterprise를 참고하세요.

더 알아보기 (Learn more)