패키지 레지스트리에 인증하기
패키지 파일 게시하기
- 같은 이름 또는 버전으로 패키지 게시
  - 중복 일반 패키지 허용 안 함
패키지 파일 다운로드
CI/CD를 사용하여 일반 패키지 게시하기
- 일반 패키지 샘플 프로젝트
문제 해결
- HTTP 403 오류
- S3에 대용량 파일 업로드 시 내부 서버 오류

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 범위로 구성되어야 합니다. 프로젝트 액세스 토큰은 최소한 개발자 역할을 가져야 합니다.
동일한 패키지 이름과 버전 아래에서 여러 파일을 업로드하려고 시도할 때 이 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 --fail-with-body --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"

<!-- 또는 전체 경로 파일로 -->

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

속성 select가 없는 예시 응답:

{
  "message":"201 Created"
}

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

curl --fail-with-body --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 15.0에서 Developer에서 Maintainer로.

필수 역할 변경됨: GitLab 17.0에서 Maintainer에서 Owner로.

사용자가 중복 일반 패키지를 게시하지 못하도록 하려면, GraphQL API 또는 UI를 사용할 수 있습니다.

UI에서:

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

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

패키지 파일 다운로드

패키지 파일을 다운로드합니다.

같은 이름, 버전 및 파일 이름을 가진 여러 패키지가 있는 경우, 가장 최근의 패키지가 검색됩니다.

전제 조건:

API 인증이 필요합니다.
- 배포 토큰으로 인증하는 경우, read_package_registry 및/또는 write_package_registry 범위가 구성되어야 합니다.
- 프로젝트 액세스 토큰은 read_api 범위와 최소한 Reporter 역할이 필요합니다.
객체 스토리지가 활성화된 GitLab 인스턴스에서 아티팩트를 다운로드할 때 cURL을 사용하는 경우, 요청이 리디렉션될 수 있으므로 --location 매개변수를 사용하세요.

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

속성	유형	필수	설명
`id`	integer/string	예	프로젝트의 ID 또는 URL 인코딩된 경로.
`package_name`	string	예	패키지 이름.
`package_version`	string	예	패키지 버전.
`file_name`	string	예	파일 이름.

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

개인 접근 토큰

개인 접근 토큰을 사용하는 예제 요청:

# 헤더 인증
curl --fail-with-body --output file.txt --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/24/packages/generic/my_package/0.0.1/file.txt"

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

CI_JOB_TOKEN

CI_JOB_TOKEN을 사용하는 예제 요청:

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

# 기본 인증
curl --fail-with-body --output file.txt --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 --fail-with-body --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 요청의 크기를 5 GB로 제한합니다. 객체 스토리지 연결 설정에서 aws_signature_version이 2로 설정되어 있는 경우, 5 GB 제한을 초과하는 패키지 파일을 게시하려고 시도하면 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'
}

GitLab 일반 패키지 저장소

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

패키지 파일 게시하기

같은 이름 또는 버전으로 패키지 게시

중복 일반 패키지 허용 안 함

패키지 파일 다운로드

CI/CD를 사용하여 일반 패키지 게시하기

일반 패키지 샘플 프로젝트

문제 해결

HTTP 403 오류

S3에 대용량 파일 업로드 시 내부 서버 오류

도움말

기능 사용 가능성과 제품 평가판

도움받기