자체 호스팅 러너에서 GitHub 호스팅 러너로 마이그레이션하기

현재 CI 인프라를 평가하고 워크플로우를 자체 호스팅 러너에서 GitHub 호스팅 러너로 마이그레이션하는 방법을 알려드릴게요. GitHub 호스팅 러너 또는 자체 호스팅 러너에서 워크플로우를 실행할 수 있고, 러너 유형을 혼합해서 사용할 수도 있어요.

출처: 문서

본문

이 튜토리얼은 현재 러너 사용을 평가한 다음, 워크플로우를 자체 호스팅 러너에서 GitHub 호스팅 러너로 효율적으로 마이그레이션하는 방법을 보여줍니다.

1. Assess your current CI infrastructure

자체 호스팅 러너에서 GitHub 호스팅 대형 러너로 마이그레이션하는 것은 현재 CI 인프라에 대한 철저한 평가에서 시작돼요. 사양과 환경을 신중하게 일치시키는 시간을 투자하면 서로 다른 러너에서 워크플로우를 실행하기 시작할 때 문제를 고치는 데 드는 시간을 최소화할 수 있어요.

CPU 코어, RAM, 스토리지, 칩 아키텍처, 운영 체제를 포함해서 워크플로우를 실행하는 데 사용되는 각 머신 사양의 인벤토리를 만드세요.
러너 중 일부가 러너 그룹의 일부이거나 레이블이 있는지 기록하세요. 이 정보를 사용해서 워크플로우를 새 러너로 마이그레이션하는 것을 단순화할 수 있어요.
워크플로우가 의존하는 사용자 지정 이미지와 사전 설치된 의존성을 문서화하세요. 이것들이 마이그레이션 전략에 영향을 미칠 거예요.
현재 자체 호스팅 러너를 대상으로 하는 워크플로우가 무엇이고 왜 그런지 식별하세요. 예를 들어 GitHub Actions 사용량 지표에서 Jobs 탭을 사용하고 러너 레이블(예: self-hosted 또는 사용자 지정 레이블)로 필터링해서 어떤 저장소와 job이 해당 레이블을 사용하는지 확인하세요. 특정 워크플로우 파일을 검증해야 한다면 코드 검색을 사용해서 runs-on: self-hosted 또는 다른 자체 호스팅 레이블을 참조하는 워크플로우 파일을 찾을 수도 있어요.
개인 네트워크 리소스(예: 내부 패키지 레지스트리, 비공개 API, 데이터베이스, 온프레미스 서비스)에 접근하는 워크플로우를 식별하세요. 이러한 워크플로우는 추가 네트워킹 구성이 필요할 수 있어요.

2. Map your processing requirements to GitHub-hosted runner types

GitHub는 Linux, Windows, macOS의 여러 운영 체제에서 관리형 러너를 제공하며, GPU 지원 머신 옵션도 있어요. Larger runners reference 문서를 참고하세요.

인벤토리의 각 고유 머신 사양을 적절한 GitHub 호스팅 러너 사양에 매핑하세요.
적합한 GitHub 호스팅 러너가 없는 자체 호스팅 러너를 기록해 두세요.
자체 호스팅 러너에서 계속 실행해야 하는 워크플로우는 마이그레이션 계획에서 제외하세요.

3. Estimate capacity requirements

GitHub 호스팅 러너를 프로비저닝하기 전에 워크플로우에 필요한 컴퓨팅 용량을 추정하세요. 현재 자체 호스팅 러너 사용량을 검토하면 적절한 러너 크기를 선택하고, 동시성 한도를 설정하고, 잠재적인 비용 변화를 예측하는 데 도움이 돼요.

GitHub 오른쪽 위에서 프로필 사진을 클릭한 다음 Organizations을 클릭하세요.
조직 이름을 클릭하세요.
조직 이름 아래에서 Insights를 클릭하세요.
"Insights" 내비게이션 메뉴에서 Actions Usage Metrics를 클릭하세요.
보려는 지표가 포함된 탭을 클릭하세요. About GitHub Actions metrics 문서를 참고하세요.
호스팅 러너 용량을 추정하기 위해 다음 데이터 포인트를 검토하세요.
- Total minutes consumed(총 소비 분): 기본 컴퓨팅 수요를 추정하는 데 도움이 돼요.
- Number of workflow runs(워크플로우 실행 수): 더 많은 동시성이 필요할 수 있는 피크 활동 시간을 식별해요.
- Job distribution across OS types(OS 유형별 job 분포): Linux, Windows, macOS 러너의 올바른 조합을 프로비저닝하도록 보장해요.
- Runner labels / Jobs tab(러너 레이블 / Jobs 탭): 러너 레이블로 필터링해서 레이블이 어디에 사용되는지 이해해요.
조사 결과를 용량 계획으로 변환하세요.
- 높은 사용량 워크플로우를 적절한 경우 더 큰 러너 크기로 매칭하세요.
- 실행 시간을 줄일 수 있는 사전 빌드 또는 사용자 지정 이미지의 이점을 얻을 수 있는 워크플로우를 식별하세요.
- 일반적으로 동시에 실행되는 job 수를 결정해서 동시성을 추정하세요.
공백을 기록해 두세요.
- 현재 호스팅 러너 이미지가 지원하지 않는 하드 의존성이 있는 워크플로우.
- 비정상적으로 긴 실행 시간 또는 독특한 환경 요구사항이 있는 job. (이 경우 사용자 지정 이미지가 필요할 수 있어요.)

용량 계획은 얼마나 많은 러너를 프로비저닝할지, 어떤 머신 유형을 사용할지, 다음 단계에서 러너 그룹과 정책을 어떻게 구성할지 안내해 줘요.

4. Configure runner groups and policies

용량 요구를 추정한 후 러너 그룹과 접근 정책을 구성해서 GitHub 호스팅 러너가 올바른 조직과 워크플로우에 사용될 수 있게 하세요.

러너를 프로비저닝하기 전에 러너 그룹을 구성하면 마이그레이션이 실수로 접근을 너무 광범위하게 열거나 예상치 못한 비용 증가를 만들지 않도록 보장해 줘요.

엔터프라이즈 수준에서 러너 그룹을 만들어서 호스팅 러너를 사용할 수 있는 대상을 정의하세요. Controlling access to larger runners 문서를 참고하세요.

러너 그룹을 사용해서 조직, 저장소 또는 워크플로우별로 접근 범위를 지정하세요. 자체 호스팅 러너에서 마이그레이션하는 경우 가능하면 기존 러너 그룹 이름이나 레이블을 재사용하는 것을 고려하세요. 이렇게 하면 GitHub 호스팅 러너로 전환할 때 워크플로우가 변경 없이 계속 작동할 수 있어요.
새 GitHub 호스팅 러너를 적절한 그룹에 추가하고 3단계에서 식별한 사용량 패턴에 따라 동시성 한도를 설정하세요. 자동 확장에 대한 자세한 내용은 Managing larger runners 문서를 참고하세요.
러너가 의도된 워크플로우에서만 사용되도록 정책 설정을 검토하세요. 예를 들어 특정 저장소로 사용을 제한하거나 신뢰할 수 없는 워크플로우가 더 강력한 머신 유형에 접근하지 못하게 방지할 수 있어요.

5. Set up GitHub-hosted runners

다음으로 이전에 식별한 머신 유형과 용량을 기반으로 GitHub 호스팅 러너를 프로비저닝하세요.

워크플로우 요구사항과 일치하는 머신 크기와 운영 체제를 선택하세요. 사용 가능한 이미지와 사양은 Larger runners reference 문서를 참고하세요.
각 러너를 러너 그룹에 할당하고 동시에 실행할 수 있는 job 수를 제어하도록 동시성 한도를 구성하세요.
이미지 유형을 선택하세요.
- 유지 관리되고 자주 업데이트되는 환경을 위해 GitHub 관리 이미지(GitHub-managed images)를 사용하세요.
- 설정 시간을 줄이기 위해 사전 설치된 의존성이 필요할 때 사용자 지정 이미지를 사용하세요. Using custom images 문서를 참고하세요.
환경 변수, 소프트웨어 설치, 시작 스크립트 같은 필요한 사용자 지정을 적용하세요. 더 많은 예시는 Customizing GitHub-hosted runners 문서를 참고하세요.
선택적으로, 러너가 내부 리소스에 접근해야 한다면 개인 네트워킹(Private networking)을 구성하세요. Private networking with GitHub-hosted runners 문서를 참고하세요.

Configure private connectivity options

워크플로우가 개인 리소스(예: 내부 패키지 레지스트리, 비공개 API, 데이터베이스, 온프레미스 서비스)에 접근해야 한다면 네트워크와 보안 요구사항에 맞는 방식을 선택하세요.

Configure Azure Private Networking

내부 리소스에 안전하게 접근하기 위해 Azure Virtual Network(VNET) 내에서 GitHub 호스팅 러너를 실행하세요.

Azure Virtual Network(VNET)를 만들고 러너를 위한 서브넷과 네트워크 보안 그룹을 구성하세요.
러너 그룹에 대해 Azure 개인 네트워킹을 활성화하세요. Configuring private networking for GitHub-hosted runners in your enterprise 문서를 참고하세요.
인바운드 및 아웃바운드 트래픽을 제어하도록 NSG 및 방화벽 규칙 같은 네트워크 구성을 적용하세요.
개인 네트워킹으로 구성된 러너 그룹을 사용하도록 워크플로우 대상을 업데이트하세요.

자세한 지침은 다음을 참고하세요.

Connect using a WireGuard overlay network

Azure 개인 네트워킹이 적용되지 않는 경우(예: 대상 네트워크가 온프레미스이거나 다른 클라우드에 있기 때문에) WireGuard 같은 VPN 오버레이를 사용해서 개인 리소스에 네트워크 수준 접근을 제공할 수 있어요.

자세한 지침과 예시는 Using WireGuard to create a network overlay 문서를 참고하세요.

Use OIDC with an API gateway for trusted access to private resources

러너가 개인 네트워크에 가입할 필요가 없다면 OIDC를 사용해서 API 게이트웨이를 통해 노출하는 서비스에 신뢰할 수 있는 수명이 짧은 접근을 설정할 수 있어요. 이 방식은 수명이 긴 secret의 필요성을 줄이고 워크플로우가 필요로 하는 특정 엔드포인트로 네트워크 접근을 제한할 수 있어요.

자세한 지침과 예시는 Using an API gateway with OIDC 문서를 참고하세요.

6. Update workflows to use the new runners

GitHub 호스팅 러너를 구성한 후 워크플로우 파일을 업데이트해서 새 러너를 대상으로 하세요.

자체 호스팅 러너가 사용했던 것과 같은 러너 그룹 이름으로 새 러너를 할당했다면 기존 레이블을 재사용하세요. 이 경우 워크플로우는 변경 없이 자동으로 새 러너를 사용해요.

새 러너 그룹이나 레이블을 만들었다면 워크플로우 YAML 파일의 runs-on 필드를 업데이트하세요. 예를 들어:

jobs:
  build:
    runs-on: [github-larger-runner, linux-x64]
    steps:
      - name: Checkout code
        uses: actions/checkout@v6
      - name: Build project
        run: make build

자체 호스팅 레이블(self-hosted, linux-x64 또는 사용자 지정 레이블 같은)에 대한 하드 코딩된 참조가 있는지 확인하고 적절한 GitHub 호스팅 러너 레이블로 교체하세요.
각 업데이트된 워크플로우를 테스트해서 새 러너에서 올바르게 실행되는지 확인하세요. 환경 차이 또는 누락된 의존성과 관련된 문제를 모니터링하세요.

7. Remove unused self-hosted runners

워크플로우를 GitHub 호스팅 러너에서 업데이트하고 테스트한 후 더 이상 필요하지 않은 자체 호스팅 러너를 제거하세요. 이렇게 하면 job이 실수로 오래된 인프라를 대상으로 하는 것을 방지할 수 있어요. Removing self-hosted runners 문서를 참고하세요.

자체 호스팅 러너를 제거하기 전에 완전히 마이그레이션했는지 확인하세요.

GitHub Actions 사용량 지표에서 Jobs 탭을 사용하고 러너 레이블(예: self-hosted 또는 사용자 지정 레이블)로 필터링해서 어떤 저장소나 job도 여전히 자체 호스팅 러너를 사용하지 않는지 확인하세요.

자체 호스팅 러너에서 GitHub 호스팅 러너로 마이그레이션하기