패키지 레지스트리에 인증
패키지 파일 게시
- 동일한 이름 또는 버전으로 패키지를 공개하는 경우
  - 중복된 일반 패키지를 허용하지 않음
패키지 파일 다운로드
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 범위로 구성해야 합니다. 프로젝트 액세스 토큰은 적어도 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 --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를 사용할 수 있습니다. 이러한 이전 패키지 개정본을 삭제하려면 패키지 API 또는 UI를 사용하는 것을 고려하세요.

중복된 일반 패키지를 허용하지 않음

변경된 필수 역할: 개발자에서 GitLab 15.0에서 유지자로 변경
변경된 필수 역할: 유지자에서 소유자로 GitLab 17.0에서 변경

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

UI에서:

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

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

패키지 파일 다운로드

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

다수의 패키지가 동일한 이름, 버전 및 파일명을 가지고 있다면 가장 최근 것이 검색됩니다.

전제 조건:

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

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

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

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

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 변수에 다시 쓰기.

문제 해결

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'
}

GitLab 일반 패키지 저장소

패키지 레지스트리에 인증

패키지 파일 게시

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

중복된 일반 패키지를 허용하지 않음

패키지 파일 다운로드

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

일반 패키지 샘플 프로젝트

문제 해결

HTTP 403 오류

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

도움말

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

도움받기