とりあえず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です。
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を使っているチームにはオススメできると思います。