More than 5 years have passed since last update.

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

Last updated at 2018-09-27Posted at 2018-09-27

はじめに

前回ドキュメントを作成するための環境を整えましたが、引き続き複数人でドキュメントを管理していく方法を考えます。
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を設定します。

build.ps1

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を選択すればいいです。