• 패키지 레지스트리에 인증
• 패키지 파일 게시
  • 동일한 이름 또는 버전으로 패키지를 게시하는 경우
    • 중복된 일반 패키지를 허용하지 마세요
• 패키지 파일 다운로드
• CI/CD를 사용하여 일반 패키지 발행
  • 일반 패키지 샘플 프로젝트
• 문제 해결
  • S3로 대형 파일을 업로드할 때 내부 서버 오류

GitLab 일반 패키지 리포지터리

• GitLab 13.5에서 소개된 기능으로 generic_packages이라는 플래그로 기본적으로 활성화됨.
• GitLab 14.8에서 generic_packages 피처 플래그가 제거됨.

프로젝트의 패키지 레지스트리에 릴리스된 실행 파일과 같은 일반적인 파일을 게시한 후, 필요할 때마다 의존성으로 사용하려면 패키지를 설치하면 됩니다.

패키지 레지스트리에 인증

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

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

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

패키지 파일 게시

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

전제 조건:

• API로 인증해야 합니다. 배포 토큰으로 인증하는 경우 write_package_registry 스코프로 구성되어 있어야 합니다. 개인 액세스 토큰이나 프로젝트 액세스 토큰으로 인증하는 경우 api 스코프로 구성되어 있어야 합니다. 프로젝트 액세스 토큰은 적어도 Developer 역할이 있어야 합니다.
• 동일한 패키지 이름과 버전 아래에 여러 파일을 업로드하려고 할 때 이 API 엔드포인트를 연속적으로 호출해야 합니다. 새로운 패키지 이름과 버전에 동시에 여러 파일을 동시에 업로드하려는 시도는 패키지를 생성해야 하는 요청이 경주하여 HTTP 500: 내부 서버 오류 응답으로 일부 실패를 겪을 수 있습니다.

PUT /projects/:id/packages/generic/:package_name/:package_version/:file_name?status=:status

요청 본문에 파일 콘텐츠를 제공합니다.

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

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에서 요구된 역할이 개발자(Developer)에서 유지보수자(Maintainer)로 변경됨.

중복된 일반 패키지를 게시하는 사용자를 방지하려면 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

파일 내용은 응답 본문에서 제공됩니다. 응답 콘텐츠 유형은 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 runner에서는 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'
}