はてなの金次郎

Pythonエンジニアの技術系ブログ

.gitlab-ci.ymlの俺的Tips

はじめに

GitLab Advent Calendar 2018 9日目の記事です。

qiita.com

GitLabを使いはじめて1年半になりますが、.gitlab-ci.yml に関するノウハウがほどほどに溜まってきた気がするのでTipsとしてまとめてみました。

注意

  • Webアプリケーションの CI/CD に関するTipsが多いです。
  • .gitlab-ci.yml の例は Python/Django で書いていますが、特に難しいことは書いていないつもりです。適宜得意な言語に置き換えて読んでください。
  • 本記事では公式ドキュメントに倣い、 .gitlab-ci.yml の一つの実行単位を ジョブ、ジョブに定義する imagestage, script などのジョブのふるまいを キーワード と呼びます。
  • 補足 は読まなくても大丈夫です。気になる方は目を通してみてください。
  • だいぶ前に書き上げてはいたので意図してはないのですが、8日目の@mikiTさんの記事と重複する部分があります。

Index

  1. Services:コンテナイメージを複数扱う
  2. Anchors:ジョブのテンプレートでスリムなYAML
  3. Predefined variables:用意されているGitLab CI/CD変数を活用する
  4. Only and Except:制限付きのジョブを作成する
  5. when:manual:安心安全なデプロイ
  6. artifactsカバレッジレポートを可視化する

Tips

1. Services:コンテナイメージを複数扱う

docs.gitlab.com

services というキーワードを用いると、ベースイメージと接続可能なコンテナを定義できます。 Docker in DockerでコンテナレジストリにDockerイメージをプッシュしたり、単体テストでデータベースコンテナに接続したりするといったケースに有用です。

例えば、下記のように定義することで postgres というホスト名でPostgreSQLに接続できます。

services:
  - postgres:latest
variables:
  POSTGRES_DB: custom_db
  POSTGRES_USER: custom_user
  POSTGRES_PASSWORD: custom_password

PostgreSQLの公式イメージで用意されている環境変数にデータベース名、ユーザ名、パスワードを設定します。

環境変数に関する詳細はPostgreSQLのDockerHubを参照してください。
FYI: https://hub.docker.com/_/postgres/

DATABASE_URL で接続情報を表すと、 postgres://$POSTGRES_USER:$POSTGRES_PASSWORD@postgres:5432/$POSTGRES_DB となります。

2. Anchors:ジョブのテンプレートでスリムなYAML

docs.gitlab.com

Anchorsという機能を利用してジョブのテンプレートを作成することで、.gitlab-ci.yml をスリムに保つことができます。

例えば、test1, test2というテストをそれぞれ実行したいとき、

test1:
  stage: test
  image: python:latest
  before_script:
    - pipenv install --dev --system
  script:
    - pytest test1

test2:
  stage: test
  image: python:latest
  before_script:
    - pipenv install --dev --system
  script:
    - pytest test2

上記のように書くこともできますが、Anchorsを利用すると下記のように書くことができます。

.test_template: &test_definition
  stage: test
  image: python:latest
  before_script:
    - pipenv install --dev --system

test1:
  <<: *test_definition
  script:
    - pytest test1

test2:
  <<: *test_definition
  script:
    - pytest test2

今回の例では行数的な差があまり出ませんでしたが、ジョブが増えれば増えるほどAnchorsの効果が高まります。

〜補足〜
現段階では同じキーワードをテンプレートとジョブで重複して定義した場合、テンプレートのキーワードは実行されずジョブのキーワードが上書きされます。

stageimage であれば別にそれでも良いのですが、 before_scriptscript, after_script は実行するコマンド数が膨らみやすく、その一部分だけ共通しているといったケースがあります。

そんなときにコマンド単位のテンプレートが定義できると便利です。 探してみたらissueは起票されていたのでいつか機能追加されるかもしれません。
FYI: https://gitlab.com/gitlab-org/gitlab-ce/issues/24235

ちなみに、👍の数が多いほど注目度が高い人気のissueとしてコミッターやコントリビュータの目に止まりやすくなるので機能追加の優先度が上がるかもしれません。

追加してほしい機能だなと思った方は 👍しておくとよいかもしれません。

3. Predefined variables:用意されているGitLab CI/CD変数を活用する

docs.gitlab.com

.gitlab-ci.yml にはGitLabがあらかじめ用意している環境変数がいくつかあります。 それらを活用することで余計な環境変数定義をしなくて済んだり、別のプロジェクトでそのまま活用できたりします。

例えば、GitLabコンテナレジストリへのイメージのプッシュで Predefined variables を活用することができます。

build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
  script:
    - docker build --pull -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
  only:
    - tags

CI_JOB_TOKEN, CI_REGISTRY, CI_REGISTRY_IMAGE, CI_COMMIT_TAG は Predefined variablesです。

4. Only and Except:制限付きのジョブを作成する

docs.gitlab.com

onlyexcept というキーワードを定義すると、ある条件の場合のみジョブを実行したり、ある条件を除く場合のみジョブを実行したりすることができます。

例えば、タグがプッシュされた時だけ実行するように定義したり、

only:
  - tags

ある特定のブランチがプッシュされた時は実行をしないように定義したりすることができます。

except:
  - master

また、正規表現にも対応しているので特定のプレフィックスがついたブランチがプッシュされた時だけ実行するというような定義も可能です。

only:
  - /^release-.*$/

5. when:manual:安心安全なデプロイ

docs.gitlab.com

when:manual をジョブに定義すると、手動で実行ボタンをクリックしたらジョブが実行されるようになります。

f:id:gyuuuutan:20181202012650p:plain
ジョブにwhen:manualを定義したときのパイプライン

上記は when:manual をデプロイジョブに定義した際のパイプラインですが、プッシュしただけではデプロイジョブは実行されません。
「▶️」の実行ボタンを押すことで初めてデプロイジョブが実行されます。

これは本番環境へのデプロイジョブに有用で、不慮の事故を防ぐことができます。

6. artifacts:カバレッジレポートを可視化する

artifacts キーワードはジョブで生成された成果物をダウンロード可能にしたり、GitLab Pagesで公開したりするときに有用です。

例えば、下記のように定義すると、ユニットテストで生成されるカバレッジレポートをパイプラインからダウンロードできるようになります。

script:
  - pytest --cov-report=html
artifacts:
  paths:
    - htmlcov

f:id:gyuuuutan:20181202012834p:plain
ジョブにartifactsを定義したときのパイプライン

〜補足〜
カバレッジレポートはGitLab Pagesの機能を利用することで真価を発揮します。

GitLab Pages は GitHub Pagesと同じような機能ですが、 GitLabのリポジトリから静的サイトを公開するための機能です。

無料で利用できたり、httpsに対応していたりといった特徴があります。

docs.gitlab.com

GitLab Pages は以下の3ステップを行うだけで静的サイトを自動で生成してくれます。

  1. public という名前のディレクトリに静的ファイルを配置する。
  2. .gitlab-ci.yml にデプロイのジョブを定義する
  3. 定義したジョブを実行する

下記のURLは上記の3ステップで自動生成された実際のURLです。
カバレッジレポートを展開しています。

https://jumpyoshim.gitlab.io/django-polls

生成されたカバレッジレポートを public ディレクトリに配置し artifactspaths に定義するだけです。

ここで注意しなければならないのが deploy ステージでないとGitLab Pagesのドメインを生成してくれないことです。(どうしてもうまくいかなくて数時間悩まされました。)

pages:
  stage: deploy
  image: alpine:latest
  script:
    - mv htmlcov/ public/
  artifacts:
    paths:
      - public
  only:
    - master

FYI: https://gitlab.com/help/user/project/pages/index.md

参考例

上記のTipsを活用した .gitlab-ci.yml の例です。 以下を実行しています。

  • GitLabコンテナレジストリへのDockerイメージのプッシュ
  • ユニットテスト
  • 文法チェック
  • コードメトリクス計測
  • Herokuへのデプロイ
  • GitLab Pagesの公開設定

FYI: https://gitlab.com/jumpyoshim/django-polls/blob/master/.gitlab-ci.yml

.build_template: &build_definition
  stage: build
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY

build_for_master:
  <<: *build_definition
  script:
    - docker build --pull -t $CI_REGISTRY_IMAGE:latest .
    - docker push $CI_REGISTRY_IMAGE:latest
  only:
    - master

build_for_tags:
  <<: *build_definition
  script:
    - docker build --pull -t $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
  only:
    - tags

.test_template: &test_definition
  stage: test
  image: python:3.7
  before_script:
    - pip install pipenv
    - pipenv install --system --dev
  except:
    - master

pytest:
  <<: *test_definition
  services:
    - postgres:latest
  variables:
    POSTGRES_DB: custom_db
    POSTGRES_USER: custom_user
    POSTGRES_PASSWORD: custom_password
  script:
    - export DATABASE_URL=postgres://$POSTGRES_USER:$POSTGRES_PASSWORD@postgres:5432/$POSTGRES_DB
    - python3 manage.py collectstatic --noinput
    - pytest --cov-report=html --tb=line
  after_script:
    - mv htmlcov/ public/
  artifacts:
    paths:
      - public

flake8:
  <<: *test_definition
  script:
    - flake8

radon:
  <<: *test_definition
  script:
    - radon cc -n C .
    - radon mi -n B .

deploy:
  stage: deploy
  image: ruby:2.5
  script:
    - gem install dpl
    - dpl --provider=heroku --app=$HEROKU_APP --api-key=$HEROKU_API_KEY --skip-cleanup
  only:
    - tags
  when: manual

pages:
  stage: deploy
  image: alpine:latest
  script:
    - echo 'Upload the coverage report'
  artifacts:
    paths:
      - public
  only:
    - master

おわりに

俺的と書いてありますがたくさんのドキュメントや記事、職場のエンジニア、GitLabコミュニティの方の助けで得ることができたTipsです。この場を借りてお礼申し上げます。
OSSへのコントリビュートなど、何かしらの形で恩返しをしていきたいと思っています。

ドキュメント

記事

GitLabコミュニティ

GitLabに関する機能や豆知識を7つ厳選してみました。
もしよろしければのぞいてみてください。

qiita.com