Gitlab CI/CDでpoetryの環境をキャッシュする方法

はじめに
#

Poetryではpoetry config virtualenvs.in-project trueを設定すると、project内に.venvを作って環境分離をしてくれます。

$ tree -L 1 -a
.
├── app/
├── dockerfiles/
├── .dockerignore
├── .gitlab-ci.yml
├── poetry.lock
├── pyproject.toml
├── README.md
└── .venv/

Gitlab CI/CDではこの.venvをキャッシュすることで、外部ライブラリ(pip)の毎回のinstallを避けて高速化することができます。

.venvを別のjob(別ディレクトリ)で再利用することは、必ず動作が保証されている訳ではないので注意しましょう。 https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93367

1. dockerfileの作成
#

image内部で仮想環境を作りたくないので、poetry installはせず、poetryのコマンドを使えるようにだけしておきます。

FROM python:3.12

ENV PYTHONUNBUFFERED=1
ENV PATH="/root/.local/bin:$PATH"

RUN curl -sSL https://install.python-poetry.org | python3 -

RUN poetry config virtualenvs.in-project true

POETRY_VIRTUALENVS_IN_PROJECTの環境変数で外部から設定してもOKです。docs

2. `.gitlab-ci.yml`の作成
#

作成したimageを$CI_REGISTRY_IMAGE/ci/python312:latestとしてgitlabのコンテナレジストリに保存して、Gitlab CI/CDで利用します。

キャッシュ専用のjobprepare_cacheを用意しpoetry installを実施することで、以降のjobではキャッシュされた.venvを利用することができます。

複数のpythonのverを検証したい等で.venvを使い分ける必要がある場合は、prefix: ci-python312を変更することで分離できます。またbranch毎など、動的に使い分けたい場合はdocsを参照ください。

.python_cache:
  image: $CI_REGISTRY_IMAGE/ci/python312:latest
  cache:
    key:
      files:
        - poetry.lock
      prefix: ci-python312 # Want to change the scope of the cache　-> https://docs.gitlab.com/ee/ci/caching/#common-use-cases-for-caches
    policy: pull
    paths:
      - .venv
      # - mypy_cache # Uncomment if you use mypy

prepare_cache:
  extends: .python_cache
  stage: cache
  cache:
    policy: pull-push
  script:
    - poetry install -v

small_test:
  extends: .python_cache
  stage: test
  script:
    - poetry run python -m pytest
  needs:
    - prepare_cache