컨테이너 레지스트리 작업

패키지 네임스페이스 https://ghcr.io를 사용하는 Container registry에 Docker 및 OCI 이미지를 저장하고 관리할 수 있습니다.

누가 이 기능을 사용할 수 있나요?

GitHub Packages는 GitHub Free, GitHub Pro, 조직용 GitHub Free, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 이상을 이용해 사용할 수 있습니다.
GitHub Packages는 레거시 리포지토리별 플랜을 사용하는 계정이 소유한 프라이빗 리포지토리에서 사용할 수 없습니다. 또한 레거시 리포지토리별 계획을 사용하는 계정은 세분화된 권한을 지원하는 레지스트리에 액세스할 수 없습니다. 이러한 계정은 리포지토리에서 청구되기 때문입니다. 세분화된 권한을 지원하는 레지스트리 목록은 "GitHub 패키지에 대한 사용 권한 정보"을 참조하세요. 자세한 내용은 “GitHub의 플랜”를 참조하세요.

이 문서의 내용

Container registry 정보

Container registry는 조직 또는 개인 계정 내에 컨테이너 이미지를 저장하고 이미지를 리포지토리와 연결할 수 있습니다. 리포지토리에서 사용 권한을 상속할지 또는 리포지토리와 독립적으로 세분화된 권한을 설정할지 선택할 수 있습니다. 퍼블릭 컨테이너 이미지에 익명으로 액세스할 수도 있습니다.

Container registry 지원 정보

Container registry는 현재 다음 컨테이너 이미지 형식을 지원합니다.

Docker 이미지를 설치하거나 게시할 때 Container registry는 Windows 이미지와 같은 외부 레이어를 지원합니다.

Container registry에 인증

GitHub Packages은(는) personal access token (classic)을(를) 사용하는 인증만 지원합니다. 자세한 내용은 "개인용 액세스 토큰 관리"을(를) 참조하세요.

프라이빗, 내부, 퍼블릭 패키지를 게시, 설치, 삭제하려면 액세스 토큰이 필요합니다.

GitHub Packages 또는 GitHub API에 인증하는 데 personal access token (classic)을 사용할 수 있습니다. personal access token (classic)을(를) 만들 때 필요에 따라 토큰의 범위를 다르게 할당할 수 있습니다. personal access token (classic)의 패키지 관련 범위에 대한 자세한 내용은 "GitHub 패키지에 대한 사용 권한 정보"을 참조하세요.

GitHub Actions 워크플로 내에서 GitHub Packages 레지스트리에 인증하려면 다음을 사용할 수 있습니다.

  • 워크플로 리포지토리와 연결된 패키지를 게시하려면 GITHUB_TOKEN을 사용합니다.
  • 다른 프라이빗 리포지토리(GITHUB_TOKEN는 액세스할 수 없음)와 연결된 패키지를 설치하기 위해 최소 read:packages 범위의 personal access token (classic).

GitHub Actions 워크플로에서 인증

이 레지스트리는 세분화된 권한을 지원합니다. 세분화된 권한을 지원하는 레지스트리는 GitHub Actions 워크플로가 personal access token을(를) 사용하여 레지스트리에 인증하는 경우, GITHUB_TOKEN로 워크플로를 업데이트하는 것을 권장합니다. personal access token로 레지스트리에 인증하는 워크플로를 업데이트하는 방법에 대한 지침은 "GitHub Actions를 사용하여 패키지 게시 및 설치"을 참조하세요.

참고: GitHub Actions 워크플로에서 REST API를 사용하여 패키지를 삭제하고 복원하는 기능은 현재 공개 미리 보기 버전이며 변경될 수 있습니다.

토큰이 패키지에 대해 admin 권한이 있는 경우, GitHub Actions 워크플로에서 GITHUB_TOKEN로 REST API를 사용하여 패키지를 삭제하거나 복원할 수 있습니다. 워크플로를 사용하여 패키지를 게시하는 리포지토리와 패키지에 명시적으로 연결한 리포지토리에는 리포지토리의 패키지에 대한 admin 권한이 자동으로 부여됩니다.

GITHUB_TOKEN의 자세한 내용은 "자동 토큰 인증"을 참조하세요. 작업에서 레지스트리를 사용하는 모범 사례에 대한 자세한 내용은 "GitHub Actions에 대한 보안 강화"을 참조하세요.

GitHub Codespaces및 GitHub Actions에 대한 패키지의 액세스 권한을 독립적으로 부여하도록 선택할 수도 있습니다. 자세한 내용은 "패키지의 액세스 제어 및 표시 여부 구성" 및 "패키지의 액세스 제어 및 표시 여부 구성"을 참조하세요.

personal access token (classic)을(를) 사용하여 인증

GitHub Packages은(는) personal access token (classic)을(를) 사용하는 인증만 지원합니다. 자세한 내용은 "개인용 액세스 토큰 관리"을(를) 참조하세요.

  1. 수행하려는 작업에 대한 적절한 범위를 사용하여 새 personal access token (classic)을(를) 만듭니다. 조직에 SSO가 필요한 경우 새 토큰에 대해 SSO를 사용하도록 설정해야 합니다.

    참고: 기본적으로 사용자 인터페이스에서 personal access token (classic)의 write:packages 범위를 선택하면 repo 범위도 선택됩니다. repo 범위는 불필요하고 광범위한 액세스를 제공하므로 특히 GitHub Actions 워크플로에 사용하지 않는 것이 좋습니다. 자세한 내용은 "GitHub Actions에 대한 보안 강화"을(를) 참조하세요. 이 문제를 해결하려면 다음 URL https://github.com/settings/tokens/new?scopes=write:packages로 사용자 인터페이스에서 personal access token (classic)의 write:packages 범위만 선택하면 됩니다.

    • 컨테이너 이미지를 다운로드하고 해당 메타데이터를 읽으려면 read:packages 범위를 선택합니다.
    • 컨테이너 이미지를 다운로드하고 업로드하며 해당 메타데이터를 읽고 쓸 write:packages 범위를 선택합니다.
    • 컨테이너 이미지를 삭제하려면 delete:packages 범위를 선택하세요.

    자세한 내용은 "개인용 액세스 토큰 관리"을(를) 참조하세요.

  2. personal access token (classic)을(를) 저장합니다. 토큰을 환경 변수로 저장하는 것이 좋습니다.

    export CR_PAT=YOUR_TOKEN

  3. 컨테이너 유형에 대한 CLI를 사용하여 ghcr.io에서 Container registry 서비스에 로그인합니다.

    $ echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin
> Login Succeeded

컨테이너 이미지 푸시

이 예제에서는 최신 버전의 IMAGE_NAME을 푸시합니다.

docker push ghcr.io/NAMESPACE/IMAGE_NAME:latest

NAMESPACE를 이미지의 범위로 지정할 개인 계정 또는 조직의 이름으로 바꿉니다.

이 예제에서는 이미지의 2.5 버전을 푸시합니다.

docker push ghcr.io/NAMESPACE/IMAGE_NAME:2.5

패키지를 처음 게시할 때 기본 표시 여부는 프라이빗입니다. 표시 유형 또는 액세스 권한을 변경하려면 "패키지의 액세스 제어 및 표시 여부 구성"을 참조하세요. 사용자 인터페이스 또는 명령줄을 사용하여 게시된 패키지를 리포지토리에 연결할 수 있습니다. 자세한 내용은 "리포지토리를 패키지에 연결"을(를) 참조하세요.

명령줄에서 컨테이너 이미지를 푸시하는 경우 이미지는 기본적으로 리포지토리에 연결되지 않습니다. ghcr.io/octocat/my-repo:latest과(와) 같이 리포지토리의 이름과 일치하는 네임스페이스로 이미지에 태그를 지정하는 경우에도 마찬가지입니다.

리포지토리를 컨테이너 패키지에 연결하는 가장 쉬운 방법은 워크플로에서 ${{secrets.GITHUB_TOKEN}}을(를) 사용하여 패키지를 게시하는 것입니다. 이 경우 워크플로가 포함되 리포지토리가 자동으로 연결됩니다. 이전에 패키지를 동일한 네임스페이스로 푸시했지만 패키지를 연결하지 않은 경우 GITHUB_TOKEN에는 패키지를 푸시할 수 있는 권한이 없습니다.

명령줄에서 이미지를 게시할 때 리포지토리를 연결하고 GitHub Actions 워크플로를 사용할 때 GITHUB_TOKEN에 적절한 권한이 부여되도록 하려면 org.opencontainers.image.source라는 레이블을 Dockerfile에 추가하는 것이 좋습니다. 자세한 내용은 이 문서에서 "컨테이너 이미지 레이블 지정" 및 "GitHub Actions를 사용하여 패키지 게시 및 설치"을(를) 참조하세요.

컨테이너 이미지 풀

다이제스트별로 풀

항상 동일한 이미지를 사용하려면 digest SHA 값으로 풀(pull)하려는 정확한 컨테이너 이미지 버전을 지정할 수 있습니다.

  1. 다이제스트 SHA 값을 찾으려면 docker inspect 또는 docker pull을 사용하고 Digest: 뒤의 SHA 값을 복사합니다.

    docker inspect ghcr.io/NAMESPACE/IMAGE_NAME

    NAMESPACE를 이미지의 범위로 지정된 개인 계정 또는 조직의 이름으로 바꿉니다.

  2. 필요에 따라 이미지를 로컬로 제거합니다.

    docker rmi  ghcr.io/NAMESPACE/IMAGE_NAME:latest

  3. 이미지 이름 뒤의 @YOUR_SHA_VALUE를 사용하여 컨테이너 이미지를 풀합니다.

    docker pull ghcr.io/NAMESPACE/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs

이름별로 풀

docker pull ghcr.io/NAMESPACE/IMAGE_NAME

NAMESPACE를 이미지의 범위로 지정된 개인 계정 또는 조직의 이름으로 바꿉니다.

이름 및 버전별로 풀

이름 및 1.14.1 버전 태그로 풀한 이미지를 보여 주는 Docker CLI 예제:

$ docker pull ghcr.io/NAMESPACE/IMAGE_NAME:1.14.1
> 5e35bd43cf78: Pull complete
> 0c48c2209aab: Pull complete
> fd45dd1aad5a: Pull complete
> db6eb50c2d36: Pull complete
> Digest: sha256:ae3b135f133155b3824d8b1f62959ff8a72e9cf9e884d88db7895d8544010d8e
> Status: Downloaded newer image for ghcr.io/NAMESPACE/IMAGE_NAME/release:1.14.1
> ghcr.io/NAMESPACE/IMAGE_NAME/release:1.14.1

NAMESPACE를 이미지의 범위로 지정된 개인 계정 또는 조직의 이름으로 바꿉니다.

이름 및 최신 버전별로 풀

$ docker pull ghcr.io/NAMESPACE/IMAGE_NAME:latest
> latest: Pulling from NAMESPACE/IMAGE_NAME
> Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344
> Status: Downloaded newer image for ghcr.io/NAMESPACE/IMAGE_NAME:latest
> ghcr.io/NAMESPACE/IMAGE_NAME:latest

NAMESPACE를 이미지의 범위로 지정된 개인 계정 또는 조직의 이름으로 바꿉니다.

컨테이너 이미지 빌드

이 예제에서는 hello_docker 이미지를 빌드합니다.

docker build -t hello_docker .

컨테이너 이미지 태그 지정

  1. 태그를 지정할 Docker 이미지의 ID를 찾습니다.

    $ docker images
> REPOSITORY                                            TAG                 IMAGE ID            CREATED             SIZE
> ghcr.io/my-org/hello_docker         latest            38f737a91f39        47 hours ago        91.7MB
> hello-world                                           latest              fce289e99eb9        16 months ago       1.84kB

  2. 이미지 ID와 원하는 이미지 이름 및 호스팅 대상을 사용하여 Docker 이미지에 태그를 지정합니다.

    docker tag 38f737a91f39 ghcr.io/NAMESPACE/NEW_IMAGE_NAME:latest

NAMESPACE를 이미지의 범위로 지정할 개인 계정 또는 조직의 이름으로 바꿉니다.

컨테이너 이미지 레이블 지정

미리 정의된 주석 키로 설명, 라이선스 및 원본 리포지토리를 포함한 메타데이터를 컨테이너 이미지에 추가할 수 있습니다. 지원되는 키의 값이 이미지의 패키지 페이지에 표시됩니다.

대부분 이미지의 경우 Docker 레이블을 사용하여 주석 키를 이미지에 추가할 수 있습니다. 자세한 내용은 공식 Docker 설명서에서 레이블과 opencontainers/image-spec 리포지토리의 미리 정의된 주석 키를 참조하세요.

다중 아키텍처 이미지의 경우 이미지 매니페스트의 annotations 필드에 적절한 주석 키를 추가하여 이미지에 설명을 추가할 수 있습니다. 자세한 내용은 "다중 아키텍처 이미지에 설명 추가"를 참조하세요.

Container registry에서는 다음 주석 키가 지원됩니다.

키설명
org.opencontainers.image.source패키지와 연결된 리포지토리의 URL입니다. 자세한 내용은 "리포지토리를 패키지에 연결"을(를) 참조하세요.
org.opencontainers.image.description텍스트 전용 설명은 512자로 제한됩니다. 이 설명은 패키지 페이지에서 패키지의 이름 아래에 표시됩니다.
org.opencontainers.image.licenses"MIT"와 같은 SPDX 라이선스 식별자는 256자로 제한됩니다. 라이선스는 패키지 페이지의 "세부 정보" 사이드바에 표시됩니다. 자세한 내용은 SPDX 라이선스 목록을 참조하세요.

키를 Docker 레이블로 추가하려면 Dockerfile에서 LABEL 명령을 사용하는 것이 좋습니다. 예를 들어 사용자 octocat이고 my-repo를 소유했으며 이미지가 MIT 라이선스 조건에 따라 배포되는 경우 다음 줄을 Dockerfile에 추가합니다.

LABEL org.opencontainers.image.source=https://github.com/octocat/my-repo
LABEL org.opencontainers.image.description="My container image"
LABEL org.opencontainers.image.licenses=MIT

참고: 리포지토리에 연결된 패키지를 게시하는 경우, 패키지는 자동으로 연결된 리포지토리의 액세스 권한을 상속받고, 조직에서 액세스 권한의 자동 상속을 사용하지 않도록 설정하지 않은 한 연결된 리포지토리의 GitHub Actions 워크플로에 패키지에 대한 액세스 권한이 자동으로 부여됩니다. 자세한 내용은 "패키지의 액세스 제어 및 표시 여부 구성"을(를) 참조하세요.

또는 docker build 명령을 사용하여 빌드 시 이미지에 레이블을 추가할 수 있습니다.

$ docker build \
 --label "org.opencontainers.image.source=https://github.com/octocat/my-repo" \
 --label "org.opencontainers.image.description=My container image" \
 --label "org.opencontainers.image.licenses=MIT"

다중 아키텍처 이미지에 설명 추가

다중 아키텍처 이미지는 여러 아키텍처를 지원하는 이미지입니다. 이 이미지는 단일 매니페스트 내에서 각각 다른 아키텍처를 지원하는 이미지 목록을 참조하여 작동합니다.

다중 아키텍처 이미지의 패키지 페이지에 표시되는 설명은 이미지 매니페스트의 annotations 필드에서 가져옵니다. Docker 레이블과 마찬가지로, 주석은 메타데이터를 이미지와 연결하는 방법을 제공하고 미리 정의된 주석 키를 지원합니다. 자세한 내용은 opencontainers/image-spec 리포지토리에서 주석을 참조하세요.

다중 아키텍처 이미지에 대한 설명을 제공하려면 다음과 같이 매니페스트의 annotations 필드에 org.opencontainers.image.description 키의 값을 설정합니다.

"annotations": {
  "org.opencontainers.image.description": "My multi-arch image"
}

예를 들어 다음 GitHub Actions 워크플로 단계는 다중 아키텍처 이미지를 빌드하고 푸시합니다. outputs 매개 변수는 이미지에 대한 설명을 설정합니다.

# 이 워크플로는 GitHub에서 인증되지 않은 작업을 사용합니다.
# 작업은 타사에서 제공하며
# 별도의 서비스 약관, 개인정보처리방침, 지원 설명서에서 규정됩니다.
# 참조하세요.

- name: Build and push Docker image
  uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
  with:
    context: .
    file: ./Dockerfile
    platforms: ${{ matrix.platforms }}
    push: true
    outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=My multi-arch image

문제 해결

  • Container registry의 각 계층에 대한 크기 제한은 10GB입니다.
  • Container registry의 업로드 시간 제한은 10분입니다.