MkDocsとAzure DevOpsでCI/CD環境を整える

はじめに

前回ドキュメントを作成するための環境を整えましたが、引き続き複数人でドキュメントを管理していく方法を考えます。
merkdown形式でドキュメントが作成できるようになったので、ExcelやWordに比べて差分チェックが容易になりました。
というわけでGitで管理しましょう、GitHub(クローン)を利用してGitHub Flowで運用するとレビューもやりやすくなってステキです。
ドキュメントに対するレビュー文化を根付かせることで不可解な仕様を事前に指摘＆排除できるようにしましょう。

また、PullRequestを経由してのmergeさせることで設計者以外が自由にドキュメントを修正することができるようになります。
設計者に求めることはドキュメントに対しての責任を負うことで、ドキュメントを作成することではありません。
直接的な仕様に関わらないtypoや分かりづらい表現などは誰が修正しても同じです。気付いた人がその場でパパっと修正できるような仕組みが理想です。

Azure DevOpsでプロジェクトを作成する

Azure DevOpsでプロジェクトを作成してください。
今回はCI/CDを行うことが目的なのでVersion controlもWork item processもなんでもいいです。

PullRequest作成時に自動でビルドする

PipeLines > Buildsから新しいビルドパイプラインを作成します。

タスクを設定する

Select a source

今回はGitHubのリポジトリを利用します。
PullRequestをトリガーとするのでDefault branch for manual and scheduled buildsは初期値で構いません。

Select a template

MkDocs用のテンプレートがあるわけではないので空のテンプレートを選択します。

Pipeline

良い感じの名前を設定し、Agent poolにHosted VS2017を選択します。
　※Pythonが動作する環境であれば他のAgentでも構いません。

Get sources

Report build statusにチェックを入れるとPullRequestにステータスが表示されるようになるのでチェックを入れましょう。

Agent Job

MkDocsでビルドする

PowerShellタスクを追加し、InlineにMkDocsをビルドするためのScriptを記載するか、ScriptファイルのPathを設定します。

pip install mkdocs
pip install mkdocs-material
mkdocs build
ls ./site

ビルド成果物をコピーし公開する

Copy and Publish Build Artifactsタスクを追加し、site配下をすべてコピーし公開するようにします。

タスク設定完了

最終的にはこんな感じになります。

PullRequest検証のトリガーを設定する

Enable pull request validationにチェックを入れ、フィルタの設定を行います。
初期設定だとmasterに対してのPullRequestだけが対象になります。
すべてのbranchに対して有効にしたい場合は*を設定しましょう。
除外したいbranchがある場合はTypeをExcludeにしてbranchを選択すればいいです。

PullRequestからの動作確認

適当にPullRequestを作成すると自動でビルドパイプラインが動作します。

正常にビルドが終了するとArtifactsから成果物を取得することができます。

masterへのpush時に自動でビルドしデプロイする

ビルドパイプラインを作成する

PullRequest作成時に自動でビルドするときと同様にPipeLines > Buildsから新しいビルドパイプラインを作成します。
タスクの設定まで全く同じなので、ExportしてからImport a pipelineで作成するとちょっとだけ楽です。

masterに対するCIのトリガーを設定する

Enable continuous integrationにチェックを入れます。

リリースパイプラインを作成する

PipeLines > Releasesから新しいリリースパイプラインを作成します。

Select a template (releases)

今回はAzure App Serviceに対してデプロイするので、Azure App Service deploymentのテンプレートを選択します。

成果物を選択する

Add an artifactからリリース対象の成果物を選択します。

masterに対するCDのトリガーを設定する

稲妻アイコンからトリガーを設定します。

タスクを設定する (release)

ステージの1 job, 1 taskをクリックしてタスクを設定します。

Stage

デプロイ先のAzure App Serviceの設定をします。

Deploy Azure App Service

デプロイするパッケージを設定します。

サンプル

• リポジトリ(GitHub)
• デプロイ先(Azure App Service)

TODO

• 画像の差し替え
• markdownlintのルール設定
• textlintの利用とルール設定
• PlantUMLを利用した図の作成
• 特定のファイルが更新されたときのみ動作するパイプラインの設定