はじめてのGitLab-CI

とりあえずGitLab-CIを使ってみたくて、簡単なジョブを実行させてみたお話。

GitLab-CIを始める前の設定はこちらの記事を参照してください。

ビルドジョブの概要

以前よりドキュメントをmarkdownで記述し、S3の静的ウェブサイトホスティング機能を使ってドキュメントを公開していました。

ドキュメントはgitでバージョン管理して、MkDocsを使ってhtml化し、S3にアップロードしています。

今回は、この作業をGitLab-CIを使って行います。

実行環境

• GitLab 8.7.5
• GitLab-CI Multi Runner 1.4.1

GitLab-CIの設定ファイル.gitlab-ci.yml作成

GitLab-CIによるビルドを行うときは、gitリポジトリのルートに.gitlab-ci.ymlを置いてビルド手順を記述します。

.gitlab-ci.ymlの書き方について詳しく知りたい方は、
GitLabの公式ドキュメントをご一読ください。

本記事では、とりあえずGitLab-CIでジョブを実行できるようになることが目的のため、今回記述した.gitlab-ci.ymlに範囲を絞って説明します。

以下が今回記述した.gitlab-ci.ymlです。

.gitlab-ci.yml

image: python:2.7

stages:
  - build
  - test
  - deploy

before_script:
    - pip install --upgrade pip

build_job1:
  stage: build
  script:
    - pip install --upgrade mkdocs
    - mkdocs build
  artifacts:
    paths:
      - site/

test_job1:
  stage: test
  variables:
    AWS_ACCESS_KEY_ID: "your-aws-access-key-id"
    AWS_SECRET_ACCESS_KEY: "your-aws-secret-access-key"
  script:
    - pip install --upgrade awscli
    - aws s3 sync --dryrun --delete ${CI_PROJECT_DIR}/site s3://your-bucket-name/

deploy_job1:
  stage: deploy
  variables:
    AWS_ACCESS_KEY_ID: "your-aws-access-key-id"
    AWS_SECRET_ACCESS_KEY: "your-aws-secret-access-key"
  script:
    - pip install --upgrade awscli
    - aws s3 sync --delete ${CI_PROJECT_DIR}/site s3://your-bucket-name/
  only:
    - master

順に説明していきます。

image

image: python:2.7

ビルドジョブを実行する環境となるDockerイメージを指定します。

ビルドジョブは、markdown形式のドキュメントをHTMLに変換するMkDocsと、変換したドキュメントをS3にアップロードするAWS CLIに依存します。

いずれもpython製であるため、今回はpythonのDockerイメージを利用します。

ビルド環境の雛形となるDockerイメージは、Docker Hubで探すことができます。

stages

stages:
  - build
  - test
  - deploy

ビルドは、ステージごとに逐次実行されます。
各ステージは複数のジョブを設定することができます。
同じステージの各ジョブは並列実行されます。

ここでは、ビルドの工程としてbuild,test,deployと3つのステージがあり、各ステージをこの順番で実行することを指定しています。

before_script

before_script:
    - pip install --upgrade pip

before_script:には、すべてのジョブの前に必ず実行されるスクリプトを記述できます。

今回はpipのupgradeを行っています。

このほか、after_script:でジョブの最後に実行されるスクリプトを記述することもできます。

stage, script, artifacts

build_job1:
  stage: build
  script:
    - pip install --upgrade mkdocs
    - mkdocs build
  artifacts:
    paths:
      - site/

build_job1:以下で、ジョブの内容を記述しています。
ジョブの名前は任意に設定できます。

stage:では、先ほどstages:で宣言したステージのうち、どのステージのジョブかを指定します。

script:では、ジョブの内容を記述していきます。

artifacts:は、ジョブの実行結果を他のジョブで使うための指定です。

ここでは、mkdocs buildでmarkdownをhtmlに変換していますが、この時、site/ディレクトリにhtmlが出力されます。
この後のジョブで、出力されたhtmlをS3にアップロードしたいので、site/を
artifactsとして指定しています。

variables, only

deploy_job1:
  stage: deploy
  variables:
    AWS_ACCESS_KEY_ID: "your-aws-access-key-id"
    AWS_SECRET_ACCESS_KEY: "your-aws-secret-access-key"
  script:
    - pip install --upgrade awscli
    - aws s3 sync --delete ${CI_PROJECT_DIR}/site s3://your-bucket-name/
  only:
    - master

deployステージのジョブで、variables:とonly:について説明します。

deployステージでは、S3にビルドされたhtmlをアップロードしていますが、このジョブはmasterブランチのビルド結果でしか実行したくありません。

このような場合にonly:を指定します。

ここではonly:にmasterブランチを指定しているので、このジョブはmasterブランチに対するビルドでしか実行されません。

only:の反対、すなわち特定のブランチ以外で実行する、といった指定をすることもできます。この場合はexcept:を使います。

only:やexcept:では、ブランチ名だけでなく、以下のようにタグ名や、正規表現を指定することもできます。

only:
  - v1.0.0
except:
  - /^feature.*$/

deployステージでは、AWS CLIを使ってS3にhtmlをアップロードしています。

AWS CLIでは、認証の際にAWS_ACCESS_KEY_IDとAWS_SECRET_ACCESS_KEYを環境変数として設定しておくと、その環境変数の値を使って認証を行います。

ジョブで環境変数を設定する場合は、variables:を使用します。
環境変数名: 値の形式でジョブ実行時の環境変数を指定することができます。

所感

GitLab-CIはGitLabに統合されているため、GitLabでソース管理をしている場合はとても簡単に使い始めることができます。

それまではWebHookでJenkinsを使ったCIを行っていましたが、GitLabとの連携の設定が複雑でした。

GitLab-CIは一旦設定すれば、.gitlab-ci.ymlをリポジトリに追加するだけで簡単にCIを行うことができます。
また、今回は簡単なタスクの説明でしたが、頑張ればもっと複雑なタスクも実行できるので、GitLabを使っているチームにはオススメできると思います。