GitLab 일반 패키지 저장소

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

프로젝트의 패키지 레지스트리에 릴리스 이진 파일과 같은 일반 파일을 게시한 후, 필요할 때 패키지를 설치하세요.

패키지 레지스트리에 인증하기

패키지 레지스트리에 인증하려면 개인 액세스 토큰, CI/CD 작업 토큰, 또는 배포 토큰이 필요합니다.

일반 패키지 API에서는 표준 API 인증 매커니즘 외에도 다른 사용 가능한 매커니즘을 지원하지 않는 도구에 사용하기 위해 HTTP 기본 인증으로 인증할 수 있습니다. user-id는 확인되지 않으며 어떤 값이든 사용할 수 있고, password는 개인 액세스 토큰, CI/CD 작업 토큰, 또는 배포 토큰이어야 합니다.

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

패키지 파일 게시하기

패키지 파일을 게시할 때, 패키지가 존재하지 않는 경우 패키지가 생성됩니다.

전제 조건:

  • API로 인증해야 합니다. 배포 토큰으로 인증하는 경우 write_package_registry 스코프로 구성해야 합니다. 개인 액세스 토큰이나 프로젝트 액세스 토큰으로 인증하는 경우 api 스코프로 구성해야 합니다. 프로젝트 액세스 토큰은 적어도 Developer 역할이 있어야 합니다.
  • 동일한 패키지 이름과 버전 아래에 여러 파일을 업로드하려는 경우 이 API 엔드포인트를 연속적으로 호출해야 합니다. 새 패키지 이름과 버전으로 동시에 여러 파일을 동시에 업로드하려는 시도는 패키지를 생성하기 위한 요청 경쟁으로 인해 HTTP 500: Internal Server Error 응답과 부분적인 실패를 겪을 수 있습니다. 
PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?status=:status
속성 유형 필수여부 설명
id 정수/문자열 예 프로젝트의 ID 또는 URL 인코딩된 경로.
package_name 문자열 예 패키지 이름. 소문자 (a-z), 대문자 (A-Z), 숫자 (0-9), 점 (.), 하이픈 (-), 또는 밑줄 (_)만 포함할 수 있습니다.
package_version 문자열 예 패키지 버전. 다음 정규식이 이를 유효성 검사합니다: \A(\.?[\w\+-]+\.?)+\z. 버전 문자열을 Rubular에서 테스트할 수 있습니다.
file_name 문자열 예 파일 이름. 소문자 (a-z), 대문자 (A-Z), 숫자 (0-9), 점 (.), 하이픈 (-), 또는 밑줄 (_)만 포함할 수 있습니다.
status 문자열 아니요 패키지 상태. default 또는 hidden이 될 수 있습니다. 숨겨진 패키지는 UI나 패키지 API 목록 엔드포인트에 표시되지 않습니다.
select 문자열 아니요 응답 페이로드. 기본값은 응답이 비어 있는 것입니다. 유효한 값은: package_file. package_file은 이 요청에 의해 생성된 패키지 파일 레코드의 세부 정보를 반환합니다.

요청 본문에 파일 콘텍스트를 제공하세요.

개인 액세스 토큰을 사용한 예시 요청: 

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

속성 select이 없는 예시 응답: 

{
  "message":"201 Created"
}

속성 select = package_file이 있는 예시 요청: 

curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --user "<username>:<Project Access Token>" \
     --upload-file path/to/file.txt \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt?select=package_file"

속성 select = package_file이 있는 예시 응답: 

{
  "id": 1,
  "package_id": 1,
  "created_at": "2021-10-12T12:05:23.387Z",
  "updated_at": "2021-10-12T12:05:23.387Z",
  "size": 0,
  "file_store": 1,
  "file_md5": null,
  "file_sha1": null,
  "file_name": "file.txt",
  "file": {
    "url": "/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b/packages/26/files/36/file.txt"
  },
  "file_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "verification_retry_at": null,
  "verified_at": null,
  "verification_failure": null,
  "verification_retry_count": null,
  "verification_checksum": null,
  "verification_state": 0,
  "verification_started_at": null,
  "new_file_path": null
}

동일한 이름 또는 버전으로 패키지를 게시하는 경우

동일한 이름과 버전을 가진 패키지를 게시하면, 새로운 패키지 파일이 기존 패키지에 추가됩니다. 중복된 제네릭 패키지를 설치할 때 GitLab은 가장 최신 버전을 다운로드합니다.

기존 패키지의 이전 파일에 액세스하고 보기 위해 UI 또는 API를 사용할 수 있습니다. 이전 패키지 버전들을 삭제하려면 Packages API나 UI를 사용하는 것을 고려해보세요.

중복된 제네릭 패키지 허용하지 않기

  • GitLab 13.12에서 도입됨.
  • GitLab 15.0에서 필요한 역할이 개발자에서 유지자로 변경되었습니다.

중복된 제네릭 패키지를 게시하는 것을 사용자가 방지하려면 GraphQL API나 UI를 사용할 수 있습니다.

UI에서:

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

변경 사항이 자동으로 저장됩니다.

패키지 파일 다운로드

패키지 파일을 다운로드하세요.

다중 패키지가 동일한 이름, 버전 및 파일 이름을 가지고 있는 경우, 가장 최근 것이 검색됩니다.

필수 준비 사항:

  • API로 인증해야 합니다.
    • 배포 토큰으로 인증하는 경우, read_package_registry 및/또는 write_package_registry 스코프로 구성되어야 합니다.
    • 프로젝트 액세스 토큰은 read_api 스코프 및 적어도 Reporter 역할이 필요합니다. 
GET /projects/:id/packages/generic/:package_name/:package_version/:file_name
속성 타입 필수 설명
id 정수/문자열 예 프로젝트의 ID 또는 URL-encoded path 입니다.
package_name 문자열 예 패키지 이름입니다.
package_version 문자열 예 패키지 버전입니다.
file_name 문자열 예 파일 이름입니다.

파일 내용은 응답 본문에서 제공됩니다. 응답 콘텐츠 유형은 application/octet-stream입니다.

개인 액세스 토큰을 사용하는 예시 요청: 

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

HTTP 기본 인증을 사용하는 예시 요청: 

curl --user "user:<your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt"

CI/CD를 이용하여 제네릭 패키지 게시

GitLab CI/CD에서 제네릭 패키지를 사용하려면 명령어에서 개인 액세스 토큰 대신 CI_JOB_TOKEN을 사용할 수 있습니다.

예시: 

image: curlimages/curl:latest

stages:
  - upload
  - download

upload:
  stage: upload
  script:
    - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" --upload-file path/to/file.txt "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt"'

download:
  stage: download
  script:
    - 'wget --header="JOB-TOKEN: $CI_JOB_TOKEN" ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt'

PowerShell을 사용하는 Windows 러너의 경우, upload 및 download 단계에서 curl 대신 Invoke-WebRequest 또는 Invoke-RestMethod을 사용해야 합니다.

예시: 

upload:
  stage: upload
  script:
    - Invoke-RestMethod -Headers @{ "JOB-TOKEN"="$CI_JOB_TOKEN" } -InFile path/to/file.txt -uri "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/my_package/0.0.1/file.txt" -Method put

제네릭 패키지 샘플 프로젝트

파이프라인에서 CI-CD 변수 작성 프로젝트에는 GitLab CI/CD에서 제네릭 패키지를 생성, 업로드, 다운로드하는 데 사용할 수 있는 작동 예제가 포함되어 있습니다.

또한 제네릭 패키지에 대한 세미버전을 관리하는 방법을 보여줍니다: CI/CD 변수에 저장하고, 검색하고, 증가시키고, 다운로드에 대한 테스트가 올바르게 작동할 때 CI/CD 변수에 다시 작성하는 방법을 보여줍니다.

문제 해결

S3에 큰 파일을 업로드할 때 내부 서버 오류

S3 호환 객체 저장소는 단일 PUT 요청의 크기를 5GB로 제한합니다. 만약 객체 저장소 연결 설정에서 aws_signature_version이 2로 설정되어 있다면, 5GB 제한보다 큰 패키지 파일을 발행하려고 시도하면 HTTP 500: 내부 서버 오류 응답이 발생할 수 있습니다.

S3에 큰 파일을 발행할 때 HTTP 500: 내부 서버 오류 응답을 받는다면, aws_signature_version을 4로 설정하세요: 

# 통합된 객체 저장소 설정
gitlab_rails['object_store']['connection'] = {
  # 다른 연결 설정
  'aws_signature_version' => '4'
}
# 또는
# 저장소별 양식 설정
gitlab_rails['packages_object_store_connection'] = {
  # 다른 연결 설정
  'aws_signature_version' => '4'
}