• 패키지 레지스트리에 인증
• 패키지 파일 게시
  • 동일한 이름 또는 버전의 패키지 게시
    • 중복되는 일반 패키지 허용 안 함
• 패키지 파일 다운로드
• 제네릭 패키지를 CI/CD를 사용하여 게시
  • 제네릭 패키지 예제 프로젝트
• 문제 해결
  • HTTP 403 오류
  • S3로 대형 파일 업로드 시 내부 서버 오류

GitLab 일반 패키지 리포지터리

프로젝트 패키지 레지스트리에 릴리스 이진 파일과 같은 일반 파일을 게시하고, 필요할 때 의존성으로 사용할 수 있도록 패키지를 설치하세요.

패키지 레지스트리에 인증

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

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

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

패키지 파일 게시

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

전제 조건:

• API로 인증해야 합니다.여기에서 인증하는 경우, 배포 토큰을 사용하는 경우 write_package_registry 스코프로 구성해야 합니다. 개인 액세스 토큰이나 프로젝트 액세스 토큰을 사용하는 경우 api 스코프로 구성해야 합니다. 프로젝트 액세스 토큰은 적어도 개발자 역할이 있어야 합니다.
• 동일한 패키지 이름과 버전 아래 여러 파일을 업로드하려는 경우 이 API 엔드포인트를 직렬로 호출해야 합니다. 새 패키지 이름과 버전에 동시에 여러 파일을 동시에 업로드하려는 시도는 패키지를 생성하려고 요청이 경주하여 HTTP 500: Internal Server Error 응답으로 부분 실패를 겪을 수 있습니다.

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>:<프로젝트 액세스 토큰>" \
     --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은 최신 버전을 다운로드합니다.

기본 패키지의 이전 파일을 열람하고 접근할 수 있는 API 또는 UI를 사용할 수 있습니다. 이러한 이전 패키지 버전을 삭제하려면, Packages API 또는 UI를 고려해보세요.

중복되는 일반 패키지 허용 안 함

• GitLab 15.0에서 필요한 역할 변경됨. 개발자에서 Maintainer로 변경되었습니다.
• GitLab 17.0에서 필요한 역할 변경됨. Maintainer에서 Owner로 변경되었습니다.

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

# 기본 인증
curl --user "사용자:<your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt"

# 헤더로 인증
curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt"

# 기본 인증
curl --user "gitlab-ci-token:${CI_JOB_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'

Windows 러너에서 PowerShell을 사용하는 경우 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

제네릭 패키지 예제 프로젝트

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

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

문제 해결

HTTP 403 오류

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

• 리소스에 액세스할 수 없는 경우.
• 프로젝트에 대한 패키지 레지스트리가 활성화되지 않은 경우.

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

S3로 대형 파일 업로드 시 내부 서버 오류

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

S3에 대형 파일을 게시할 때 HTTP 500: Internal Server Error 응답을 받는 경우, aws_signature_version을 4로 설정하십시오:

# 통합된 객체 스토리지 설정
gitlab_rails['object_store']['connection'] = {
  # 기타 연결 설정
  'aws_signature_version' => '4'
}
# 또는 
# 리포지터리별 형식 설정
gitlab_rails['packages_object_store_connection'] = {
  # 기타 연결 설정
  'aws_signature_version' => '4'
}