커스텀 이미지 사용하기

커스텀 이미지 사용하기

조직이나 엔터프라이즈의 GitHub 호스팅 더 큰 러너를 위해 커스텀 이미지를 만들고, 관리하고, 사용할 수 있어요. 커스텀 이미지를 사용하면 워크플로를 더 빠르게 실행하고 작업 간 일관성을 높일 수 있어요.

출처: 문서

본문

커스텀 이미지

GitHub 호스팅 더 큰 러너가 사용하는 정확한 환경을 정의하는 커스텀 이미지를 만들 수 있어요. 커스텀 이미지를 사용하면 도구, 종속성, 구성을 미리 설치해 워크플로를 빠르게 하고 작업 간 일관성을 개선할 수 있어요.

러너가 커스텀 이미지를 사용하면 "사전 워밍(pre-warmed)"된 환경처럼 작동해, 패키지와 바이너리를 워크플로를 실행할 때마다가 아니라 이미지 생성 중에 한 번 다운로드하므로 워크플로가 더 빨리 완료돼요. 커스텀 이미지에 대한 자세한 내용은 러너 이미지를 참고하세요.

커스텀 이미지를 사용하는 과정은 세 가지 주요 단계로 이루어져요:

1. 이미지 생성 러너 설정하기: 커스텀 이미지를 빌드하고 저장할 더 큰 러너를 만들어요.
2. 커스텀 이미지 생성하기: 이미지 생성 러너를 사용해 워크플로를 실행해 커스텀 이미지를 생성해요.
3. 커스텀 이미지 설치하기: 커스텀 이미지를 사용하는 러너를 만들어요.

사전 요구 사항

커스텀 이미지를 만들기 전에 다음 요구 사항이 충족되는지 확인해요.

• 정책: 조직이나 엔터프라이즈에서 커스텀 이미지가 활성화되어 있어야 해요. 엔터프라이즈 소유자는 Actions 정책 설정에서 커스텀 이미지에 대한 접근을 관리하고 보존 정책을 설정할 수 있어요. 자세한 내용은 엔터프라이즈에서 GitHub Actions에 대한 정책 시행하기를 참고하세요.

• 권한: 커스텀 이미지를 만들고 관리하려면 조직 또는 엔터프라이즈 소유자이거나, CI/CD Admin 역할을 갖거나, 다음 세밀한 권한을 가진 역할이어야 해요.

  • 조직 호스팅 러너 커스텀 이미지 보기(View organization hosted runner custom images)
  • 조직 호스팅 러너 커스텀 이미지 관리(Manage organization hosted runner custom images)
  • 조직 러너 및 러너 그룹 관리(Manage organization runners and runner groups)

  자세한 내용은 커스텀 조직 역할의 권한을 참고하세요.

이미지 생성 러너 설정하기

커스텀 이미지를 만들려면 먼저 이미지 생성 러너를 설정해야 해요. 러너를 만들 때 러너에 선택한 플랫폼이 빌드하려는 이미지의 플랫폼과 일치해야 해요. 러너의 플랫폼은 Linux x64, Linux ARM64, Windows x64가 될 수 있어요.

1. 더 큰 러너를 만들어요:
   • 조직의 경우 조직에 더 큰 러너 추가하기를 참고하세요.
   • 엔터프라이즈의 경우 엔터프라이즈에 더 큰 러너 추가하기를 참고하세요.
2. 러너를 구성할 때 이미지 생성 러너에 대해 다음 구성을 선택해요:
   • Platform: 만들 계획인 이미지의 플랫폼과 일치하는 지원되는 플랫폼을 선택해요(Linux x64, Linux ARM64, Windows x64).
   • Image: 빌드할 이미지를 선택한 다음 Enable this runner to generate custom images 체크박스를 활성화해요.
     • GitHub 소유 이미지에서 시작하거나, 깨끗한 OS에서 시작할 기본 이미지를 선택할 수 있어요.
     • 기존 커스텀 이미지를 기본 이미지로 시작해 계층화된 이미지 워크플로를 가능하게 할 수도 있어요.
     • ARM64 플랫폼의 경우 도구가 미리 설치된 ARM 유지보수 이미지를 선택할 수도 있어요.
   • Runner group: 러너가 구성원이 될 그룹을 선택해요. 커스텀 이미지가 생성되면 이 러너 그룹의 러너만 그 이미지의 새 버전을 생성할 수 있어요.

커스텀 이미지 생성하기

이미지 생성 러너를 만든 후에는 snapshot 키워드를 포함하는 워크플로를 실행해 커스텀 이미지를 생성해요.

이미지 생성을 위한 워크플로를 구성하려면:

• runs-on 값을 만든 이미지 생성 러너의 이름으로 설정해요.
• 작업에 snapshot 키워드를 추가해요. 아래에 표시된 문자열 구문 또는 매핑 구문을 사용해요.
  • snapshot 키워드를 포함하는 각 작업은 별도의 이미지를 만들어요. 이미지 또는 이미지 버전을 하나만 생성하려면 모든 워크플로 단계를 단일 작업에 포함해요.
  • snapshot 키워드를 포함하는 작업이 성공적으로 실행될 때마다 그 이미지의 새 버전이 만들어져요.

Note

GitHub은 이미지 생성을 주간 예약 워크플로로 구성할 것을 권장해요. 이 접근 방식은 종속성을 최신 상태로 유지하고 최신 보안 패치를 확보해요. 자세한 내용은 워크플로를 트리거하는 이벤트를 참고하세요.

워크플로가 완료된 후 이미지가 완전히 생성되어 사용 준비가 되기까지 시간이 걸릴 수 있어요. 프로비저닝 시간은 러너 크기와 구성에 따라 달라지며, 더 큰 러너의 경우 몇 시간이 걸릴 수 있어요.

이미지는 작업이 성공적으로 완료될 때만 생성돼요. 이는 워크플로가 실패하거나 불완전한 상태로 끝나면 새 이미지 버전이 생성되지 않도록 방지해요.

이미지가 생성되면 워크플로에서 사용할 수 있어요. 커스텀 이미지 관리에 대한 자세한 내용은 커스텀 이미지 관리하기를 참고하세요.

문자열 구문

snapshot과 함께 문자열 구문을 사용해 이미지 이름을 정의할 수 있어요. 이 방법은 새 이미지를 만들거나 같은 이름의 기존 이미지에 새 버전을 추가해요. 이 구문으로는 버전 번호를 지정할 수 없어요.

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: my-custom-image
    steps:
      # Add any steps to download and setup any dependencies here

매핑 구문

snapshot과 함께 매핑 구문을 사용해 image-name과 선택적 version을 모두 정의할 수 있어요. 메이저 버전을 지정하면, 해당 메이저 버전이 이미 존재하는 경우 마이너 버전이 자동으로 증가해요. 패치 버전은 지원되지 않아요.

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: 
        image-name: my-custom-image
        version: 2.*
    steps:
      # Add any steps to download and setup any dependencies here

조건부(conditionals)

snapshot 키워드는 snapshot 매핑 주변에서 if 키워드를 사용한 조건부 실행을 지원해요. 조건을 사용해 이미지 snapshot이 생성되는 시점을 제어할 수 있어요. 예를 들어 다음 작업은 태그 빌드에 대해 이미지 생성을 건너뛰어요.

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: 
        if: ${{ ! startsWith(github.ref, 'refs/tags/') }}
        image-name: my-custom-image
        version: 2.*
    steps:
      # Add any steps to download and setup any dependencies here

if 키워드에 대한 자세한 내용은 조건을 사용해 작업 실행 제어하기를 참고하세요.

버전 관리

커스텀 이미지를 생성할 때 GitHub은 업데이트 관리와 이미지 기록 추적을 돕기 위해 버전 번호를 자동으로 할당해요.

기본 동작

조직이나 엔터프라이즈에 지정된 이름의 이미지가 없으면 GitHub은 초기 버전 번호 1.0.0으로 이미지를 만들어요. 같은 이름의 이미지가 이미 존재하면 GitHub은 마이너 버전 번호를 증가시켜 새 버전을 만들어요(예: 1.1.0, 1.2.0 등).

YAML 파일에 버전을 지정하지 않으면 이미지 생성은 이 기본 동작을 사용해요.

워크플로에서 버전 지정하기

YAML 매핑에 버전을 포함하면 GitHub은 먼저 메이저 버전 번호를 확인해요.

• 지정된 메이저 버전이 이미 존재하면 새 이미지는 다음 마이너 버전을 사용해요(예: 1.0이 1.1이 됨).
• 메이저 버전이 없으면 GitHub은 새 메이저 버전을 만들어요(예: 2.0).

패치 버전은 지원되지 않아요.

최신 태그

이미지의 가장 최근 워크플로 실행은 항상 latest로 태그돼요. YAML에서 더 오래된 메이저 버전을 지정하면(예: 2.0 버전이 존재할 때 version: 1.*), GitHub은 더 오래된 메이저 버전 아래에 새 마이너 버전을 생성하고 이를 latest로 표시해요.

Note

GitHub 호스팅 더 큰 러너 생성은 이미지 버전 선택에서 와일드카드를 지원하지 않아요.

커스텀 이미지에서 빌드한 이미지의 만료

커스텀 이미지가 다른 커스텀 이미지에서 빌드되면, 파생 이미지는 기본 이미지의 만료 타임라인을 상속해요. 최대 버전 수명(maximum version age)은 파생 이미지가 생성된 시점이 아니라 기본 커스텀 이미지가 빌드된 시점부터 계산돼요.

예를 들어 커스텀 이미지 A가 Day 2에 빌드되고 커스텀 이미지 B가 7일 최대 버전 수명 정책으로 Day 4에 A에서 빌드된 경우, A와 B 모두 Day 9에 만료돼요.

커스텀 이미지의 청구 및 스토리지

커스텀 이미지를 사용하는 작업은 이미지를 사용하는 더 큰 러너와 동일한 분(minute)당 요금으로 청구돼요. 커스텀 이미지의 스토리지는 GitHub Actions 스토리지를 통해 별도로 청구돼요.

이미지를 자주 다시 빌드하고 이전 버전을 보존하면, snapshot 키워드를 포함하는 성공적인 각 워크플로 작업이 새 이미지 버전을 만들기 때문에 스토리지 사용량이 빠르게 늘어날 수 있어요. 자세한 내용은 GitHub Actions 청구와 엔터프라이즈에서 GitHub Actions에 대한 정책 시행하기를 참고하세요.

커스텀 이미지 관리하기

각 이미지에 대한 상세 정보를 보고, 사용하지 않는 이미지나 특정 버전을 삭제하고, 시간에 따른 이미지 버전을 추적할 수 있어요.

1. GitHub에서 조직의 메인 페이지로 이동해요.

2. 조직 이름 아래에서 Settings 탭을 클릭해요.

   

3. 왼쪽 사이드바에서 Actions을 클릭한 다음 Custom images을 클릭해요.

4. "Custom images" 페이지에서 조직이나 엔터프라이즈에서 만들어진 모든 커스텀 이미지를 볼 수 있어요.

5. 특정 이미지에 대한 세부 정보를 보려면 이미지 이름을 클릭해요.

커스텀 이미지 설치하기

커스텀 이미지가 준비되면 새 GitHub 호스팅 더 큰 러너에 설치할 수 있어요.

1. 더 큰 러너를 만드는 단계를 따라가요:

   • 조직의 경우 조직에 더 큰 러너 추가하기를 참고하세요.
   • 엔터프라이즈의 경우 엔터프라이즈에 더 큰 러너 추가하기를 참고하세요.

2. 러너를 구성할 때:

   • Platform: 이미지를 생성할 때 사용한 것과 동일한 플랫폼을 선택해요(Linux x64, Linux ARM64, Windows x64).
   • Image: Custom 탭을 선택한 다음 목록에서 커스텀 이미지를 선택해요.
     • 이미지가 보이지 않는다면 올바른 플랫폼을 선택했는지, 이미지가 생성된 것과 동일한 수준(조직 또는 엔터프라이즈)에서 러너를 만들고 있는지 확인해요.
   • Image version: Latest을 선택해 가장 최근 버전을 자동으로 사용하거나, 특정 버전 번호를 선택해 러너를 그 버전에 고정해요.
     • Latest을 선택하면 이미지의 새 버전이 제공될 때 러너가 자동으로 업데이트돼요. 러너를 특정 버전에 고정하면 나중에 업그레이드하려면 러너를 수동으로 편집해야 해요.
   • Size: 이미지 크기와 같거나 더 큰 스토리지를 가진 러너 크기를 선택해요. 예를 들어 이미지가 8코어 러너에서 생성되었다면 8코어 이상을 선택해 이 이미지를 실행해요.
   • Runner group: 이 이미지를 사용해야 하는 저장소와 공유되는 러너 그룹에 러너를 할당해요.

3. GitHub Actions 워크플로 작업에서 runs-on 키를 러너 이름으로 설정해요.

   jobs: 
     build:
       runs-on: my-custom-runner
       steps:
       # Add any steps for your workflow here
   

4. 워크플로를 실행해 성공적으로 완료되는지 확인해요. 작업 로그의 "Set up job" 섹션에 이미지 이름과 버전이 표시될 거예요.

커스텀 이미지의 보안 모범 사례

이미지에 대한 무단 변경을 방지하려면 다음 모범 사례를 따라가요.

• 이미지 생성을 위한 전용 러너 그룹을 사용해요. 프로덕션 이미지를 생성하는 러너는 전용 러너 그룹에 남아 있어야 해요. 프로덕션과 개발 또는 테스트 저장소 사이에 러너 그룹을 공유하지 마세요. 개발 또는 테스트 저장소에 접근할 수 있는 사람은 누구나 프로덕션 이미지에 악성 코드를 주입할 수 있기 때문이에요.
• 공개 저장소가 이미지 생성 러너에 접근하지 못하게 해요. 이미지 생성 러너를 사용할 수 있는 저장소를 필요한 저장소로만 제한하고, 접근을 정기적으로 검토해요.
• 저장소에 최소 권한을 적용해요. 이미지 생성 러너에 접근할 수 있는 저장소에 조직 전체 write 접근을 부여하지 마세요. 이미지는 어떤 브랜치에서든 생성될 수 있으므로, 쓰기 접근이 있는 사람은 누구나 임의 코드가 있는 브랜치를 만들어 이미지 생성을 트리거할 수 있어요.