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

Tip

2018年末に記載したドキュメントで内容が陳腐化しています。

はじめに¶

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

Select a template¶

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

Pipeline¶

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

Get sources¶

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

Agent Job¶

MkDocsでビルドする¶

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

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

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

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

タスク設定完了¶

最終的にはこんな感じになります。
設定完了

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

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