패키지 레지스트리의 PyPI 패키지
프로젝트의 패키지 레지스트리에 PyPI 패키지를 게시합니다. 그런 다음 의존성으로 사용해야 할 때마다 패키지를 설치합니다.
패키지 레지스트리는 다음과 함께 작동합니다:
pip 및 twine 클라이언트가 사용하는 특정 API 엔드포인트에 대한 문서는 PyPI API 문서를 참조하십시오.
PyPI 패키지를 빌드하는 방법을 알아보세요.
패키지 레지스트리로 인증
패키지 레지스트리에 게시하려면 먼저 인증해야 합니다.
이를 위해 다음을 사용할 수 있습니다:
-
api로 스코프가 설정된 개인 액세스 토큰 -
read_package_registry,write_package_registry, 또는 둘 다로 스코프가 설정된 배포 토큰 - CI 작업 토큰
여기에 문서화되지 않은 인증 방법을 사용하지 마십시오. 문서화되지 않은 인증 방법은 나중에 제거될 수 있습니다.
개인 액세스 토큰으로 인증
개인 액세스 토큰으로 인증하려면 ~/.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-인코딩된 경로(예: 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-인코딩된 경로(예: 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/*
GitLab에 체크인한 ~/.pypirc 파일에서도 CI_JOB_TOKEN을 사용할 수 있습니다:
[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/*
다음 메시지는 패키지가 성공적으로 게시되었음을 나타냅니다:
Uploading distributions to https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi
Uploading mypypipackage-0.0.1-py3-none-any.whl
100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.58k/4.58k [00:00<00:00, 10.9kB/s]
Uploading mypypipackage-0.0.1.tar.gz
100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.24k/4.24k [00:00<00:00, 11.0kB/s]
게시된 패키지를 보려면 프로젝트의 패키지 및 레지스트리 페이지로 이동하십시오.
.pypirc 파일을 사용하여 리포지터리 소스를 정의하지 않았다면 다음과 같이 인증하여 리포지터리에 게시할 수 있습니다:
TWINE_PASSWORD=<personal_access_token 또는 deploy_token> TWINE_USERNAME=<username 또는 deploy_token_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>
-
<package_file>은.tar.gz또는.whl로 끝나는 패키지 파일 이름입니다. -
<source_name>은 설정 중 사용한 소스 이름입니다.
동일한 이름 또는 버전으로 패키지를 발행
동일한 이름과 버전의 패키지가 이미 존재하는 경우 패키지를 발행할 수 없습니다.
먼저 기존 패키지를 삭제해야 합니다.
동일한 패키지를 여러 번 발행하려고 하면 400 Bad Request 오류가 발생합니다.
PyPI 패키지 설치
패키지 레지스트리에서 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-encoded 경로(예:group%2Fproject) 또는 프로젝트 ID(예:42) 중 하나입니다.
이 명령에서 --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/projects/<your_project_id>/packages/pypi/simple
이 메시지는 패키지가 성공적으로 설치되었음을 나타냅니다:
Looking in indexes: https://<personal_access_token_name>:****@gitlab.example.com/api/v4/projects/<your_project_id>/packages/pypi/simple
Collecting mypypipackage
Downloading 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)
Installing collected packages: mypypipackage
Successfully installed 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>
이 명령에서도 --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 정규화된 이름 (PEP-503)을 사용하는 패키지를 찾습니다. -, _, . 문자는 모두 동일하게 처리되며 반복된 문자는 제거됩니다.
my.package에 대한 pip install 요청은 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 패키지를 설치합니다.
도움말