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
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
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>:<프로젝트 액세스 토큰>" \
--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를 고려해보세요.
중복되는 일반 패키지 허용 안 함
사용자가 중복된 일반 패키지를 게시하는 것을 방지하려면 GraphQL API 또는 UI를 사용할 수 있습니다.
UI에서:
- 왼쪽 사이드 바에서 검색 또는 이동을 선택하고 그룹을 찾습니다.
- 설정 > 패키지 및 레지스트리를 선택합니다.
- 중복 패키지 테이블의 일반 행에서 중복 허용 토글을 끕니다.
- 선택 사항. 예외 텍스트 상자에 허용할 패키지의 이름과 버전과 일치하는 정규표현식을 입력합니다.
변경 사항은 자동으로 저장됩니다.
패키지 파일 다운로드
패키지 파일을 다운로드하세요.
여러 패키지가 동일한 이름, 버전 및 파일 이름을 가지는 경우, 가장 최근 것이 검색됩니다.
전제 조건:
-
API로 인증해야 합니다.
- 배포 토큰을 사용하는 경우
read_package_registry
및/또는write_package_registry
스코프로 구성해야 합니다. - 프로젝트 액세스 토큰은
read_api
스코프 및 적어도Reporter
역할이 필요합니다.
- 배포 토큰을 사용하는 경우
GET /projects/:id/packages/generic/:package_name/:package_version/:file_name
속성 | 유형 | 필수 | 설명 |
---|---|---|---|
id
| 정수/문자열 | 예 | 프로젝트의 ID 또는 URL 인코딩된 경로. |
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"
CI_JOB_TOKEN
을 사용하는 예시 요청:
# 헤더로 인증
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'
}