PyPI 패키지 레지스트리

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

프로젝트의 패키지 레지스트리에 PyPI 패키지를 게시한 후, 필요할 때마다 해당 패키지들을 종속성으로 사용할 수 있습니다.

패키지 레지스트리는 다음과 함께 작동합니다:

pip와 twine 클라이언트가 사용하는 특정 API 엔드포인트에 대한 문서는 PyPI API 문서를 참조하세요.

PyPI 패키지를 빌드하는 방법을 알아보세요.

패키지 레지스트리로 인증

패키지 레지스트리에 게시하려면 먼저 인증해야 합니다.

이를 위해 다음을 사용할 수 있습니다:

여기에 문서화되지 않은 인증 방법은 향후 제거될 수 있습니다.

개인 액세스 토큰으로 인증

개인 액세스 토큰으로 인증하려면 ~/.pypirc 파일을 편집하여 다음을 추가하세요: 

[distutils]
index-servers =
    gitlab

[gitlab]
repository = https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi
username = <your_personal_access_token_name>
password = <your_personal_access_token>

<project_id>는 프로젝트의 URL-encoded 경로(예: group%2Fproject)이거나 프로젝트 ID(예: 42)입니다.

배포 토큰으로 인증

배포 토큰으로 인증하려면 ~/.pypirc 파일을 편집하여 다음을 추가하세요: 

[distutils]
index-servers =
    gitlab

[gitlab]
repository = https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi
username = <deploy token username>
password = <deploy token>

<project_id>는 프로젝트의 URL-encoded 경로(예: group%2Fproject)이거나 프로젝트 ID(예: 42)입니다.

CI 작업 토큰으로 인증

GitLab CI/CD 내에서 PyPI 명령을 사용하려면 CI_JOB_TOKEN을 사용할 수 있습니다. 이를 사용할 수 있는 예시는 다음과 같습니다: 

image: python:latest

run:
  script:
    - pip install build twine
    - python -m build
    - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*

CI_JOB_TOKEN을 .pypirc 파일에 사용할 수도 있으며, 이 파일을 GitLab에 체크인할 수 있습니다: 

[distutils]
index-servers =
    gitlab

[gitlab]
repository = https://gitlab.example.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/pypi
username = gitlab-ci-token
password = ${env.CI_JOB_TOKEN}

그룹 내 패키지에 액세스하려면 인증

그룹 URL을 프로젝트 URL 대신 사용하여 위의 지시사항을 따라 토큰 유형을 사용할 수 있습니다: 

https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/pypi

PyPI 패키지 게시

전제 조건:

  • 패키지 레지스트리로 인증해야 합니다.
  • 버전 문자열이 유효해야 합니다.
  • 최대 허용 패키지 크기는 5GB입니다.
  • description 필드의 최대 길이는 4000자입니다. 더 긴 description 문자열은 잘립니다.
  • 동일한 버전의 패키지를 여러 번 업로드할 수 없습니다. 시도할 경우 400 Bad Request 오류가 발생합니다.
  • PyPI 패키지는 프로젝트 ID를 사용하여 게시됩니다.
  • 프로젝트가 그룹에 속한 경우, 프로젝트 레지스트리에 게시된 PyPI 패키지는 그룹 수준 레지스트리에서도 사용할 수 있습니다(자세한 내용은 그룹 레벨에서 설치 참조).

그런 다음 twine을 사용하여 패키지를 게시할 수 있습니다.

버전 문자열 유효성 검사

만약 버전 문자열(예: 0.0.1)이 유효하지 않다면, 거부됩니다. GitLab은 다음의 정규표현식을 사용하여 버전 문자열을 유효성 검사합니다. 

\A(?:
    v?
    (?:([0-9]+)!)?                                                 (?# epoch)
    ([0-9]+(?:\.[0-9]+)*)                                          (?# release segment)
    ([-_\.]?((a|b|c|rc|alpha|beta|pre|preview))[-_\.]?([0-9]+)?)?  (?# pre-release)
    ((?:-([0-9]+))|(?:[-_\.]?(post|rev|r)[-_\.]?([0-9]+)?))?       (?# post release)
    ([-_\.]?(dev)[-_\.]?([0-9]+)?)?                                (?# dev release)
    (?:\+([a-z0-9]+(?:[-_\.][a-z0-9]+)*))?                         (?# local version)
)\z}xi

이 정규표현식을 실험하고 버전 문자열을 시도할 수 있습니다. 여기에서 정규표현식 편집기를 사용해 보세요.

더 많은 정규표현식 세부 정보는 이 문서를 확인하세요.

twine을 사용하여 PyPI 패키지 게시

PyPI 패키지를 게시하려면 다음과 같이 명령을 실행하세요: 

python3 -m twine upload --repository gitlab dist/*

이 메시지는 패키지가 성공적으로 게시되었음을 나타냅니다: 

https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi로 배포 파일 업로드 중
mypypipackage-0.0.1-py3-none-any.whl 업로드 중
100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.58k/4.58k [00:00<00:00, 10.9kB/s]
mypypipackage-0.0.1.tar.gz 업로드 중
100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.24k/4.24k [00:00<00:00, 11.0kB/s]

게시된 패키지를 보려면, 프로젝트의 패키지 및 레지스트리 페이지로 이동하세요.

만약 .pypirc 파일을 사용하여 저장소 소스를 정의하지 않은 경우, 인증을 내장하여 저장소로 게시할 수 있습니다: 

TWINE_PASSWORD=<개인 액세스 토큰 또는 배포 토큰> TWINE_USERNAME=<사용자명 또는 배포 토큰 사용자명> python3 -m twine upload --repository-url https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi dist/*

이 페이지의 단계를 따르지 않았다면, 패키지가 제대로 빌드되었는지 확인하고, setuptools로 PyPI 패키지를 생성했는지 확인하세요.

그런 다음 다음 명령을 사용하여 패키지를 업로드할 수 있습니다: 

python -m twine upload --repository <source_name> dist/<package_file>

동일한 이름 또는 버전의 패키지 게시

동일한 이름과 버전의 패키지가 이미 존재하는 경우, 패키지를 게시할 수 없습니다. 먼저 기존 패키지를 삭제해야 합니다. 동일한 패키지를 여러 번 게시하려고 하면 400 Bad Request 오류가 발생합니다.

PyPI 패키지 설치

GitLab 14.2 및 이후 버전에서, 파이썬 패키지 레지스트리에서 PyPI 패키지를 찾을 수 없을 때, 요청은 pypi.org로 전달됩니다.

관리자는 이 동작을 연속 통합 설정에서 비활성화할 수 있습니다.

경고: --index-url 옵션을 사용할 때, http로 시작하는 URL의 기본 포트인 80와 같이 기본 포트를 지정하지 마십시오. 또는 https로 시작하는 URL의 기본 포트인 443를 지정하지 마십시오.

프로젝트 레벨에서 설치

패키지의 최신 버전을 설치하려면, 다음 명령을 사용하세요: 

pip install --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple --no-deps <package_name>
  • <package_name>은 패키지 이름입니다.
  • <personal_access_token_name>은 read_api 스코프가 있는 개인 액세스 토큰 이름입니다.
  • <personal_access_token>은 read_api 스코프가 있는 개인 액세스 토큰입니다.
  • <project_id>는 프로젝트의 URL 인코딩된 경로(예: group%2Fproject) 또는 프로젝트 ID(예: 42)입니다.

이 명령에서 --extra-index-url을 --index-url 대신 사용할 수 있습니다. 그러나 --extra-index-url 사용은 의존성 혼란 공격에 취약하게 만드므로 권장되지 않습니다. --extra-index-url은 사용자의 제공된 URL을 패키지가 존재하는지 확인하는 추가 레지스트리로 추가합니다. --index-url은 클라이언트가 제공된 URL에서만 패키지를 확인하도록 지시합니다.

가이드를 따르고 ‘MyPyPiPackage’ 패키지를 설치하려는 경우 다음을 실행할 수 있습니다: 

pip install mypypipackage --no-deps --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple

이 메시지는 패키지가 성공적으로 설치되었음을 나타냅니다: 

다음에서 색인 보기: https://<personal_access_token_name>:****@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple
mypypipackage를 수집 중
  https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/files/d53334205552a355fee8ca35a164512ef7334f33d309e60240d57073ee4386e6/mypypipackage-0.0.1-py3-none-any.whl (1.6 kB)을 다운로드 중
수집된 패키지: mypypipackage
성공적으로 설치됨 mypypipackage-0.0.1

그룹 레벨에서 설치하기

그룹에서 패키지의 최신 버전을 설치하려면 다음 명령을 사용하세요: 

pip install --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/groups/<group_id>/-/packages/pypi/simple --no-deps <package_name>

이 명령에서:

  • <package_name>은 패키지 이름입니다.
  • <personal_access_token_name>은 read_api 스코프를 갖는 개인 액세스 토큰 이름입니다.
  • <personal_access_token>은 read_api 스코프를 갖는 개인 액세스 토큰입니다.
  • <group_id>은 그룹 ID입니다.

위 명령에서 --index-url 대신 --extra-index-url을 사용할 수 있습니다. 그러나 --extra-index-url을 사용하면 패키지를 확인하기 위해 사용자 정의 리포지토리를 확인하기 전에 PyPi 리포지토리를 확인하여 의존성 혼란 공격을 당할 수 있습니다. --extra-index-url은 제공된 URL을 추가 레지스트리로 추가하며, 이를 통해 클라이언트가 패키지의 존재를 확인합니다. --index-url은 클라이언트에게 제공된 URL에서만 패키지를 확인하도록 지시합니다.

가이드를 따라 MyPyPiPackage 패키지를 설치하려는 경우 다음을 실행할 수 있습니다: 

pip install mypypipackage --no-deps --index-url https://<personal_access_token_name>:<personal_access_token>@gitlab.example.com/api/v4/groups/<your_group_id>/-/packages/pypi/simple

패키지 이름

GitLab은 Python normalized names (PEP-503)을 사용하는 패키지를 찾습니다. -, _, . 문자는 모두 동일하게 취급되며, 반복된 문자는 제거됩니다.

pip install 요청이 my.package를 위해 들어오면 my-package, my_package, my....package와 같은 세 가지 문자 중 하나와 일치하는 패키지를 찾습니다.

requirements.txt 사용

pip가 귀하의 공개 레지스트리에 액세스하길 원할 경우, requirements.txt 파일에 귀하의 레지스트리 URL과 함께 --extra-index-url 매개변수를 추가하세요. 

--extra-index-url https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple
package-name==1.0.0

개인 레지스트리인 경우, 몇 가지 방법으로 인증할 수 있습니다. 예를 들어:

  • 귀하의 requirements.txt 파일을 사용하여: 
--extra-index-url https://__token__:<your_personal_token>@gitlab.example.com/api/v4/projects/<project_id>/packages/pypi/simple
package-name==1.0.0
  • ~/.netrc 파일을 사용하여: 
machine gitlab.example.com
login __token__
password <your_personal_token>

문제 해결

성능을 향상시키려면 pip 명령어가 패키지와 관련된 파일을 캐시에 저장합니다. Pip는 자체적으로 데이터를 삭제하지 않습니다. 캐시는 새 패키지가 설치됨에 따라 증가합니다. 문제가 발생하면 다음 명령으로 캐시를 지워주세요: 

pip cache purge

여러 개의 index-url 또는 extra-index-url 매개변수

여러 개의 index-url 및 extra-index-url 매개변수를 정의할 수 있습니다.

동일한 도메인 이름(예: gitlab.example.com)을 서로 다른 인증 토큰과 함께 여러 번 사용하는 경우, pip가 패키지를 찾지 못할 수 있습니다. 이 문제는 명령 실행 중에 pip이 토큰을 등록하고 저장하는 방식 때문에 발생합니다.

이 문제를 해결하기 위해 모든 프로젝트 또는 그룹이나 그룹의 부모에 대상으로 하는 모든 프로젝트 또는 그룹에 대한 공통 부모 그룹에서 read_package_registry 스코프와 함께 그룹 배포 토큰을 사용할 수 있습니다.

지원되는 CLI 명령어

GitLab PyPI 리포지토리에서는 다음과 같은 CLI 명령을 지원합니다:

  • twine upload: 레지스트리에 패키지 업로드
  • pip install: 레지스트리에서 PyPI 패키지 설치