パッケージレジストリのPyPIパッケージ

プロジェクトのパッケージレジストリに PyPI パッケージを公開します。そして、依存関係として使用する必要があるときはいつでもパッケージをインストールしてください。

パッケージ・レジストリは次のように動作します:

piptwine クライアントが使用する特定の API エンドポイントのドキュメントについては、PyPI API documentationを参照してください。

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 エンコードされたパス (例: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 13.4 で導入されました

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パッケージの公開

前提条件:

その後、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 or deploy_token> TWINE_USERNAME=<username or deploy_token_username> python3 -m twine upload --repository-url https://gitlab.example.com/api/v4/projects/<project_id>/packages/pypi dist/*

このページの手順に従わなかった場合は、パッケージが正しくビルドされ、で PyPI パッケージを作成したことを確認してくださいsetuptools

その後、以下のコマンドを使ってパッケージをアップロードできます:

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

同じ名前またはバージョンのパッケージの公開

同じ名前とバージョンのパッケージがすでに存在する場合は、パッケージを公開できません。まず既存のパッケージを削除する必要があります。同じパッケージを複数回公開しようとすると、400 Bad Request エラーが発生します。

PyPI パッケージのインストール

GitLab 14.2以降では、PyPIパッケージがパッケージレジストリで見つからない場合、リクエストはpypi.orgに転送されます。

管理者は継続的インテグレーションの設定でこの動作を無効にすることができます。

caution
--index-url オプションを使用する場合、http で始まる URL の場合は80httpsで始まる 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) です。

これらのコマンドでは、--index-url.の --index-url代わりに--extra-index-url を使用することができます。--index-url しかし、.を使用すると --index-url--index-url --extra-index-url カスタムリポジトリをチェックする前に PyPi リポジトリでパッケージをチェックするため、依存性の混同攻撃に対して脆弱に --extra-index-url --index-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>

このコマンドで

  • <package_name> はパッケージ名です。
  • <personal_access_token_name> は、read_api スコープの個人アクセストークン名です。
  • <personal_access_token> は、read_api スコープの個人アクセストークンです。
  • <group_id> はグループIDです。

これらのコマンドでは、--index-url.の --index-url代わりに--extra-index-url を使う--index-urlことができます。 しかし、 を使うと --index-url--index-url --extra-index-url カスタムリポジトリをチェックする前に PyPi リポジトリでパッケージをチェックするため、依存性の混乱の攻撃に対して脆弱に --extra-index-url --index-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-packagemy_packagemy....package のような 3 文字のいずれかにマッチするパッケージを探します。

テストの拡張requirements.txt

pipに非公開レジストリにアクセスさせたい場合は、--extra-index-url パラメータとレジストリのURLをrequirements.txt ファイルに追加します。

--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見つからないことがあります。pip この問題は pip、コマンド実行時にトークンを登録・保存する方法にpip 起因 pipします。

このイシューを回避するには、index-urlextra-index-url の値で対象となるすべてのプロジェクトまたはグループに共通の親グループからスコープread_package_registry を持つグループデプロイトークンを使用することができます。

サポートされているCLIコマンド

GitLab PyPIリポジトリは以下のCLIコマンドをサポートしています:

  • twine upload:レジストリにパッケージをアップロード。
  • pip install:レジストリから PyPI パッケージをインストールします。