일반 패키지 저장소를 사용하여 릴리스 바이너리 등 일반 파일을 프로젝트의 패키지 레지스트리에 게시하고 관리하세요. 이 기능은 npm이나 Maven과 같은 특정 패키지 형식에 맞지 않는 아티팩트를 저장하고 배포하는 데 특히 유용합니다.

일반 패키지 저장소는 다음을 제공합니다:

• 모든 파일 유형을 패키지로 저장하는 공간.
• 패키지에 대한 버전 관리.
• GitLab CI/CD와의 통합.
• 자동화를 위한 API 액세스.

패키지 레지스트리 인증#

패키지 레지스트리와 상호 작용하려면 다음 방법 중 하나로 인증해야 합니다:

• 범위를 api로 설정한 개인 액세스 토큰.
• 범위를 api로 설정하고 Developer, Maintainer, 또는 Owner 역할을 가진 프로젝트 액세스 토큰.
• CI/CD 작업 토큰.
• 범위를 read_package_registry, write_package_registry, 또는 둘 다로 설정한 배포 토큰.

여기에 문서화된 방법 외의 인증 방법은 사용하지 마세요. 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.

패키지 레지스트리로 인증할 때 다음 모범 사례를 따르세요:

• Developer 역할과 관련된 권한에 액세스하려면 개인 액세스 토큰을 사용하세요.
• 자동화된 파이프라인에는 CI/CD 작업 토큰을 사용하세요.
• 외부 시스템 통합에는 배포 토큰을 사용하세요.
• 항상 HTTPS를 통해 인증 정보를 전송하세요.

HTTP Basic 인증#

표준 인증 방법을 지원하지 않는 도구를 사용하는 경우 HTTP Basic 인증을 사용할 수 있습니다:

curl --user "<username>:<token>" <other options> 

무시되지만 사용자 이름을 제공해야 합니다. 토큰은 개인 액세스 토큰, CI/CD 작업 토큰 또는 배포 토큰입니다.

패키지 게시#

API를 사용하여 패키지를 게시할 수 있습니다.

단일 파일 게시#

단일 파일을 게시하려면 다음 API 엔드포인트를 사용하세요:

PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name

URL의 플레이스홀더를 특정 값으로 교체하세요:

• :id: 프로젝트 ID 또는 URL 인코딩된 경로
• :package_name: 패키지 이름
• :package_version: 패키지 버전
• :file_name: 업로드하는 파일 이름. 아래의 유효한 패키지 파일 이름 형식을 참조하세요.

예시:

curl --location --header "PRIVATE-TOKEN: <personal_access_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

curl --location --user "<username>:<personal_access_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

curl --location --header "PRIVATE-TOKEN: <project_access_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

curl --location --user "<project_access_token_username>:project_access_token" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

curl --location --header "DEPLOY-TOKEN: <deploy_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

curl --location --user "<deploy_token_username>:<deploy_token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/1.0.0/file.txt"

publish:
  stage: deploy
  script:
    - |
      curl --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
           --upload-file path/to/file.txt \
           "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/file.txt"

publish:
  stage: deploy
  script:
    - |
      curl --location --user "gitlab-ci-token:${CI_JOB_TOKEN}" \
           --upload-file path/to/file.txt \
           "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/file.txt"

각 요청은 성공 또는 실패를 나타내는 응답을 반환합니다. 업로드가 성공하면 응답 상태는 201 Created입니다.

여러 파일 게시#

여러 파일이나 전체 디렉토리를 게시하려면 각 파일에 대해 API 호출을 한 번씩 해야 합니다.

저장소에 여러 파일을 게시할 때 다음 모범 사례를 따라야 합니다:

• 버전 관리: 패키지에 일관된 버전 관리 체계를 사용하세요. 이것은 프로젝트 버전, 빌드 번호 또는 날짜를 기반으로 할 수 있습니다.
• 파일 구성: 패키지 내에서 파일을 어떻게 구조화할지 고려하세요. 포함된 모든 파일과 그 목적을 나열하는 매니페스트 파일을 포함할 수 있습니다.
• 자동화: 가능하면 CI/CD 파이프라인을 통해 게시 프로세스를 자동화하세요. 이렇게 하면 일관성이 보장되고 수동 오류가 줄어듭니다.
• 오류 처리: 스크립트에 오류 검사를 구현하세요. 예를 들어 cURL의 HTTP 응답 코드를 확인하여 각 파일이 성공적으로 업로드되었는지 확인하세요.
• 로깅: 어떤 파일이 언제 누구에 의해 업로드되었는지 로그를 유지하세요. 이것은 문제 해결 및 감사에 중요할 수 있습니다.
• 압축: 대용량 디렉토리의 경우 업로드 전에 내용을 단일 파일로 압축하는 것을 고려하세요. 이렇게 하면 업로드 프로세스가 단순화되고 API 호출 수가 줄어듭니다.
• 체크섬: SHA256 체크섬은 업로드된 파일에 대해 자동으로 계산 및 저장됩니다. 체크섬을 사용하여 다운로드한 파일의 무결성을 확인하세요.

예시:

#!/bin/bash

TOKEN="<access_token>"
PROJECT_ID="24"
PACKAGE_NAME="my_package"
PACKAGE_VERSION="1.0.0"
DIRECTORY_PATH="./files_to_upload"

for file in "$DIRECTORY_PATH"/*; do
    if [ -f "$file" ]; then
        filename=$(basename "$file")
        curl --location --header "PRIVATE-TOKEN: $TOKEN" \
             --upload-file "$file" \
             "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/packages/generic/$PACKAGE_NAME/$PACKAGE_VERSION/$filename"
        echo "Uploaded: $filename"
    fi
done

upload_package:
  stage: publish
  script:
    - |
      for file in ./build/*; do
        if [ -f "$file" ]; then
          filename=$(basename "$file")
          curl --header "JOB-TOKEN: $CI_JOB_TOKEN" \
               --upload-file "$file" \
               "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/$filename"
          echo "Uploaded: $filename"
        fi
      done

디렉토리 구조 유지#

게시된 디렉토리의 구조를 보존하려면 파일 이름에 상대 경로를 포함하세요:

#!/bin/bash

TOKEN="<access_token>"
PROJECT_ID="24"
PACKAGE_NAME="my_package"
PACKAGE_VERSION="1.0.0"
DIRECTORY_PATH="./files_to_upload"

find "$DIRECTORY_PATH" -type f | while read -r file; do
    relative_path=${file#"$DIRECTORY_PATH/"}
    curl --location --header "PRIVATE-TOKEN: $TOKEN" \
         --upload-file "$file" \
         "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/packages/generic/$PACKAGE_NAME/$PACKAGE_VERSION/$relative_path"
    echo "Uploaded: $relative_path"
done

패키지 다운로드#

API를 사용하여 패키지를 다운로드할 수 있습니다.

단일 파일 다운로드#

단일 패키지 파일을 다운로드하려면 다음 API 엔드포인트를 사용하세요:

GET /projects/:id/packages/generic/:package_name/:package_version/:file_name

URL의 플레이스홀더를 특정 값으로 교체하세요:

• :id: 프로젝트 ID 또는 URL 인코딩된 경로
• :package_name: 패키지 이름
• :package_version: 패키지 버전
• :file_name: 업로드하는 파일 이름

예시:

curl --header "PRIVATE-TOKEN: <access_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

curl --user "<username>:<access_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

curl --header "PRIVATE-TOKEN: <project_access_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

curl --user "<project_access_token_username>:<project_access_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

curl --header "DEPLOY-TOKEN: <deploy_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

curl --user "<deploy_token_username>:<deploy_token>" \
     --location \
     "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt" \
     --output file.txt

download:
  stage: test
  script:
    - |
      curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
           --location \
           --output file.txt \
           "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/file.txt"

download:
  stage: test
  script:
    - |
      curl --user "gitlab-ci-token:${CI_JOB_TOKEN}" \
           --location \
           --output file.txt \
           "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/file.txt"

여러 파일 다운로드#

여러 파일이나 전체 디렉토리를 다운로드하려면 각 파일에 대해 API 호출을 한 번씩 하거나 추가 도구를 사용해야 합니다.

저장소에서 여러 파일을 다운로드할 때 다음 모범 사례를 따라야 합니다:

• 버전 관리: 일관성을 보장하기 위해 다운로드하려는 패키지의 정확한 버전을 항상 지정하세요.
• 디렉토리 구조: 다운로드할 때 파일 구성을 보존하기 위해 패키지의 원래 디렉토리 구조를 유지하세요.
• 자동화: 자동화된 워크플로우를 위해 CI/CD 파이프라인 또는 빌드 스크립트에 패키지 다운로드를 통합하세요.
• 오류 처리: 모든 파일이 성공적으로 다운로드되었는지 확인하는 검사를 구현하세요. HTTP 상태 코드를 확인하거나 다운로드 후 파일 존재 여부를 확인할 수 있습니다.
• 캐싱: 자주 사용되는 패키지의 경우 네트워크 사용량을 줄이고 빌드 시간을 개선하기 위해 캐싱 메커니즘 구현을 고려하세요.
• 병렬 다운로드: 파일이 많은 대용량 패키지의 경우 프로세스 속도를 높이기 위해 병렬 다운로드 구현을 고려하세요.
• 체크섬: SHA256 체크섬을 사용하여 다운로드한 파일의 무결성을 확인하세요. 체크섬은 검증을 위해 응답 헤더와 API 응답에서 제공됩니다.
• 증분 다운로드: 자주 변경되는 대용량 패키지의 경우 마지막 다운로드 이후 변경된 파일만 다운로드하는 메커니즘 구현을 고려하세요.

예시:

#!/bin/bash

TOKEN="<access_token>"
PROJECT_ID="24"
PACKAGE_NAME="my_package"
PACKAGE_VERSION="1.0.0"
OUTPUT_DIR="./downloaded_files"

# Create output directory if it doesn't exist
mkdir -p "$OUTPUT_DIR"

# Array of files to download
files=("file1.txt" "file2.txt" "subdirectory/file3.txt")

for file in "${files[@]}"; do
    curl --location --header "PRIVATE-TOKEN: $TOKEN" \
         --output "$OUTPUT_DIR/$file" \
         --create-dirs \
         "https://gitlab.example.com/api/v4/projects/$PROJECT_ID/packages/generic/$PACKAGE_NAME/$PACKAGE_VERSION/$file"
    echo "Downloaded: $file"
done

download_package:
  stage: build
  script:
    - |
      FILES=("file1.txt" "file2.txt" "subdirectory/file3.txt")
      for file in "${FILES[@]}"; do
        curl --location --header "JOB-TOKEN: $CI_JOB_TOKEN" \
             --output "$file" \
             --create-dirs \
             "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/$file"
        echo "Downloaded: $file"
      done

전체 패키지 다운로드#

패키지의 모든 파일을 다운로드하려면 다음을 해야 합니다:

1. 패키지 ID를 가져옵니다.
2. GitLab API를 사용하여 패키지 내용을 나열합니다.
3. 각 파일을 다운로드합니다.

패키지의 모든 파일을 다운로드하려면 다음 명령을 실행하세요:

TOKEN="<access_token>"
PROJECT_ID="24"
PACKAGE_NAME="my_package"
PACKAGE_VERSION="1.0.0"
GITLAB_URL="https://gitlab.example.com"
OUTPUT_DIR="./downloaded_package"

# Create output directory
mkdir -p "$OUTPUT_DIR"

# Step 1: Get the package ID
PACKAGE_ID=$(curl --location --header "PRIVATE-TOKEN: $TOKEN" \
     "$GITLAB_URL/api/v4/projects/$PROJECT_ID/packages?package_type=generic&package_name=$PACKAGE_NAME&package_version=$PACKAGE_VERSION" \
     | jq -r ".[] | select(.name==\"$PACKAGE_NAME\" and .version==\"$PACKAGE_VERSION\") | .id")

if [ -z "$PACKAGE_ID" ] || [ "$PACKAGE_ID" = "null" ]; then
    echo "Error: Package '$PACKAGE_NAME' version '$PACKAGE_VERSION' not found"
    exit 1
fi

echo "Found package ID: $PACKAGE_ID"

# Step 2: Get list of files in the package
files=$(curl --location --header "PRIVATE-TOKEN: $TOKEN" \
     "$GITLAB_URL/api/v4/projects/$PROJECT_ID/packages/$PACKAGE_ID/package_files" \
     | jq -r '.[].file_name')

if [ -z "$files" ]; then
    echo "Error: No files found in package"
    exit 1
fi

# Step 3: Download each file
for file in $files; do
    echo "Downloading: $file"
    curl --location --header "PRIVATE-TOKEN: $TOKEN" \
         --output "$OUTPUT_DIR/$file" \
         --create-dirs \
         "$GITLAB_URL/api/v4/projects/$PROJECT_ID/packages/generic/$PACKAGE_NAME/$PACKAGE_VERSION/$file"
    # Check if download was successful
    if [ $? -eq 0 ]; then
        echo "✓ Downloaded: $file"
    else
        echo "✗ Failed to download: $file"
    fi
done

echo "Package download complete"

패키지 삭제#

패키지를 삭제하기 전에 관련 보안 위험을 이해해야 합니다.

패키지를 삭제하려면 다음 중 하나를 수행할 수 있습니다:

• UI 사용.
• API 사용.

체크섬으로 파일 무결성 확인#

SHA256 체크섬은 업로드된 모든 파일에 대해 자동으로 계산되고 저장됩니다. 이 체크섬을 사용하여 다운로드한 파일의 무결성을 확인할 수 있습니다.

체크섬을 확인하려면 다음 중 하나를 수행할 수 있습니다:

• HTTP 응답 헤더에서 체크섬을 가져옵니다.
• API 응답에서 체크섬을 가져옵니다.
• CI/CD 파이프라인에 체크섬 확인을 통합합니다.

응답 헤더에서 체크섬 가져오기#

파일을 다운로드할 때 X-Checksum-SHA256 응답 헤더에서 SHA256 체크섬을 가져올 수 있습니다.

사전 요구 사항:

응답 헤더에서 체크섬을 가져오려면 다음 중 하나를 수행해야 합니다:

• 파일이 로컬에 저장되도록 오브젝트 스토리지를 비활성화합니다.
• 오브젝트 스토리지를 활성화하되 직접 다운로드를 비활성화합니다(파일은 GitLab Workhorse를 통해 제공됩니다). 오브젝트 스토리지 직접 다운로드가 활성화되면 파일이 오브젝트 스토리지 제공자로 리디렉션되어 X-Checksum-SHA256과 같은 사용자 지정 헤더를 리디렉션 응답에 포함할 수 없습니다.

# Download a file and get the checksum from the response header
curl --header "PRIVATE-TOKEN: <access_token>" \
     --location \
     --output file.txt \
     --dump-header headers.txt \
     --url "https://gitlab.example.com/api/v4/projects/1/packages/generic/my_package/0.0.1/file.txt"

# Extract the checksum from the response header
CHECKSUM=$(grep "X-Checksum-SHA256:" headers.txt | cut -d' ' -f2 | tr -d '\r')
echo "Expected checksum: $CHECKSUM"

# Verify the downloaded file
ACTUAL_CHECKSUM=$(sha256sum file.txt | cut -d' ' -f1)
if [ "$CHECKSUM" = "$ACTUAL_CHECKSUM" ]; then
    echo "✓ File integrity verified"
else
    echo "✗ File integrity check failed"
fi

API 응답에서 체크섬 가져오기#

API 호출에서 패키지 파일을 나열하여 체크섬을 가져옵니다:

# Get the package ID
PACKAGE_ID=$(curl --header "PRIVATE-TOKEN: <access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/1/packages?package_type=generic&package_name=my_package&package_version=0.0.1" \
     | jq -r ".[] | select(.name==\"my_package\" and .version==\"0.0.1\") | .id")

# Get file information, including checksums
curl --header "PRIVATE-TOKEN: <access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/1/packages/$PACKAGE_ID/package_files" \
     | jq '.[] | {file_name: .file_name, file_sha256: .file_sha256}'

CI/CD 파이프라인에서 파일 무결성 확인#

CI/CD 파이프라인에 체크섬 확인을 통합할 수 있습니다.

사전 요구 사항:

CI/CD 파이프라인에서 체크섬을 확인하려면 다음 중 하나를 수행해야 합니다:

• 파일이 로컬에 저장되도록 오브젝트 스토리지를 비활성화합니다.
• 오브젝트 스토리지를 활성화하되 직접 다운로드를 비활성화합니다(파일은 GitLab Workhorse를 통해 제공됩니다). 오브젝트 스토리지 직접 다운로드가 활성화되면 파일이 오브젝트 스토리지 제공자로 리디렉션되어 X-Checksum-SHA256과 같은 사용자 지정 헤더를 리디렉션 응답에 포함할 수 없습니다.

verify_download:
  stage: test
  script:
    - |
      # Download file and get checksum from header
      curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
           --location \
           --output file.txt \
           --dump-header headers.txt \
           "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/${CI_COMMIT_TAG}/file.txt"

      # Extract checksum from response header
      EXPECTED_CHECKSUM=$(grep "X-Checksum-SHA256:" headers.txt | cut -d' ' -f2 | tr -d '\r')

      # Calculate actual checksum
      ACTUAL_CHECKSUM=$(sha256sum file.txt | cut -d' ' -f1)

      # Verify integrity
      if [ "$EXPECTED_CHECKSUM" = "$ACTUAL_CHECKSUM" ]; then
        echo "✓ File integrity verified"
      else
        echo "✗ File integrity check failed"
        exit 1
      fi

중복 패키지 이름 게시 비활성화#

기본적으로 기존 패키지와 동일한 이름 및 버전으로 패키지를 게시하면 새 파일이 기존 패키지에 추가됩니다. 설정에서 중복 파일 이름 게시를 비활성화할 수 있습니다.

사전 요구 사항:

• Owner 역할이 있어야 합니다.

중복 파일 이름 게시를 비활성화하려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
2. 왼쪽 사이드바에서 설정 > 패키지 및 레지스트리를 선택합니다.
3. 중복 패키지 테이블의 일반 행에서 중복 허용 토글을 끕니다.
4. 선택 사항. 예외 텍스트 상자에 허용할 패키지의 이름과 버전과 일치하는 정규 표현식을 입력합니다.

패키지 보존 정책 추가#

스토리지를 관리하고 관련 버전을 유지하기 위해 패키지 보존 정책을 구현하세요.

이를 위해:

• 내장된 GitLab 정리 정책을 사용하세요.

API를 사용하여 사용자 지정 정리 스크립트를 구현할 수도 있습니다.

일반 패키지 샘플 프로젝트#

Write CI-CD Variables in Pipeline 프로젝트에는 GitLab CI/CD에서 일반 패키지를 생성, 업로드 및 다운로드하는 데 사용할 수 있는 작동 예시가 포함되어 있습니다.

또한 일반 패키지의 시맨틱 버전을 관리하는 방법도 보여줍니다: CI/CD 변수에 저장하고, 검색하고, 증가시키고, 다운로드 테스트가 올바르게 작동할 때 CI/CD 변수에 다시 쓰는 방법을 설명합니다.

유효한 패키지 파일 이름 형식#

유효한 패키지 파일 이름에는 다음이 포함될 수 있습니다:

• 문자: A-Z, a-z
• 숫자: 0-9
• 특수 문자: . (점), _ (언더스코어), - (하이픈), + (더하기), ~ (물결표), @ (골뱅이), / (슬래시)

패키지 파일 이름은 다음을 할 수 없습니다:

• 물결표(~) 또는 골뱅이(@)로 시작
• 물결표(~) 또는 골뱅이(@)로 끝남
• 공백 포함

문제 해결#

HTTP 403 오류#

HTTP 403 Forbidden 오류가 발생할 수 있습니다. 이 오류는 다음 중 하나가 발생했을 때 발생합니다:

• 리소스에 대한 액세스 권한이 없습니다.
• 프로젝트에 대해 패키지 레지스트리가 활성화되어 있지 않습니다.

문제를 해결하려면 패키지 레지스트리가 활성화되어 있고 액세스 권한이 있는지 확인하세요.

S3에 대용량 파일 업로드 시 Internal Server 오류#

S3 호환 오브젝트 스토리지는 단일 PUT 요청의 크기를 5GB로 제한합니다. 오브젝트 스토리지 연결 설정에서 aws_signature_version이 2로 설정된 경우, 5GB 제한보다 큰 패키지 파일을 게시하려고 하면 HTTP 500: Internal Server Error 응답이 발생할 수 있습니다.

S3에 대용량 파일을 게시할 때 HTTP 500: Internal Server Error 응답을 받는 경우 aws_signature_version을 4로 설정하세요:

# Consolidated Object Storage settings
gitlab_rails['object_store']['connection'] = {
  # Other connection settings
  'aws_signature_version' => '4'
}
# OR
# Storage-specific form settings
gitlab_rails['packages_object_store_connection'] = {
  # Other connection settings
  'aws_signature_version' => '4'
}