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

## はじめに

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

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

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

[Azure DevOps](https://azure.microsoft.com/ja-jp/services/devops/)でプロジェクトを作成してください。
今回はCI/CDを行うことが目的なので`Version control`も`Work item process`もなんでもいいです。

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

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

### タスクを設定する

#### Select a source

今回は[GitHub](https://github.com/Shigezo32/DocsSample)のリポジトリを利用します。
PullRequestをトリガーとするので`Default branch for manual and scheduled builds`は初期値で構いません。
![Environment-cicd_001.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/a0e6d207-df27-1a9a-695d-0af6245990d8.png)

#### Select a template

MkDocs用のテンプレートがあるわけではないので空のテンプレートを選択します。
![Environment-cicd_002.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/7f19f491-38e1-b8f9-dde4-b8618e1d7f90.png)

#### Pipeline

良い感じの名前を設定し、Agent poolに`Hosted VS2017`を選択します。
　※Pythonが動作する環境であれば他のAgentでも構いません。
![Environment-cicd_003.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/23c24626-e88b-6027-5951-bd7bd1b195c8.png)

#### Get sources

`Report build status`にチェックを入れるとPullRequestにステータスが表示されるようになるのでチェックを入れましょう。
![Environment-cicd_004.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/5c8f85ad-523d-e4c1-c49c-41b305c5aae4.png)

#### Agent Job

##### MkDocsでビルドする

PowerShellタスクを追加し、InlineにMkDocsをビルドするためのScriptを記載するか、ScriptファイルのPathを設定します。
![Environment-cicd_005.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/14eef6c4-43fe-8625-90dd-e08b6fb42951.png)
![Environment-cicd_006.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/b67fd3f6-f5af-a7b0-c6e4-47e7ac0b7b95.png)

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

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

Copy and Publish Build Artifactsタスクを追加し、site配下をすべてコピーし公開するようにします。
![Environment-cicd_007.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/ff1a1ac8-b121-28e2-7b14-b69e851650b5.png)
![Environment-cicd_008.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/c7822392-b3a0-b278-7c3f-b2cfdc76fd01.png)

#### タスク設定完了

最終的にはこんな感じになります。
![Environment-cicd_009.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/506dac35-db50-6647-8eb3-fc0f621a2772.png)

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

`Enable pull request validation`にチェックを入れ、フィルタの設定を行います。
初期設定だとmasterに対してのPullRequestだけが対象になります。
すべてのbranchに対して有効にしたい場合は`*`を設定しましょう。
除外したいbranchがある場合はTypeを`Exclude`にしてbranchを選択すればいいです。
![Environment-cicd_010.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/dd8e0a03-e169-5d0c-bfff-958261933880.png)

### PullRequestからの動作確認

適当に[PullRequest](https://github.com/Shigezo32/DocsSample/pull/1)を作成すると自動でビルドパイプラインが動作します。
![Environment-cicd_011.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/49fa3770-1c28-c62f-d79d-8d2ef22a837d.png)

正常にビルドが終了すると`Artifacts`から成果物を取得することができます。
![Environment-cicd_012.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/e3a93ff8-6f10-5e83-d432-77102f53a3d7.png)

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

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

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

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

`Enable continuous integration`にチェックを入れます。
![Environment-cicd_013.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/8d0aa99d-4203-3666-ff3e-82a44f754b20.png)

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

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

#### Select a template (releases)

今回は`Azure App Service`に対してデプロイするので、`Azure App Service deployment`のテンプレートを選択します。
![Environment-cicd_014.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/720749c0-d756-2202-d2d0-5bf032dc0c46.png)

#### 成果物を選択する

`Add an artifact`からリリース対象の成果物を選択します。
![Environment-cicd_015.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/0330e168-1dbf-8785-1c6a-8c57733c2f6a.png)

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

稲妻アイコンからトリガーを設定します。
![Environment-cicd_016.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/8472204f-a681-cfe0-b220-f29f88aa009d.png)
![Environment-cicd_017.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/566a1edd-d8e1-e3b3-0fe1-a17225ce7f3a.png)

#### タスクを設定する (release)

ステージの`1 job, 1 task`をクリックしてタスクを設定します。
![Environment-cicd_018.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/e21010bf-7121-a84e-5da2-0a0d97fc3469.png)

##### Stage

デプロイ先の`Azure App Service`の設定をします。
![Environment-cicd_019.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/d00be73b-82a3-37fe-18e2-f982818a2392.png)

##### Deploy Azure App Service

デプロイするパッケージを設定します。
![Environment-cicd_020.PNG](https://qiita-image-store.s3.amazonaws.com/0/125332/b417d8c8-992a-b32f-ffa1-717e5a2f9729.png)

## サンプル

* [リポジトリ(GitHub)](https://github.com/Shigezo32/DocsSample)
* [デプロイ先(Azure App Service)](https://mkdocs-sample.azurewebsites.net)

## TODO

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