pipelinesの説明¶

概要¶

auto-mkdocsシステム(自称)で利用するpipelines.ymlを解説する。

Pipleline環境の設定

更新時のパイプライン実行トリガーを設定する。
実行OSイメージを設定する。

Mkdocs環境の構築・HTML生成(ビルド)

Mkdocs環境構築
Mkdocs環境でのHTML生成（ビルド実行）

生成したHTMLファイルを公開先リポジトリ（リモート）にpushする

格納先のリポジトリのクローン
Git情報の確認＆設定
パイプライン上で生成したHTMLファイル(site配下)を格納先リポジトリにコピーする
ファイルを公開先リポジトリに格納する

詳細¶

1. [更新時のパイプライン実行トリガー]¶

パイプラインを実行する際のトリガーとなるブランチを設定する。

trigger:
- dataonly

2. [実行OSイメージ]¶

Mkdocsを実行するOSイメージを設定する。

#Ubuntuの最新イメージを利用する
pool:
  vmImage: ubuntu-latest

3. [Mkdocs環境構築]¶

実行OSイメージに、mkdocsパッケージをpipインストールする。 displayNameを利用して、実行時のジョブに表示名を出力する。

steps:
- script: |
    pip install mkdocs
    pip install mkdocs-material
  displayName: '**(1) Install Mkdocs **'

解説
pipコマンドでmkdocsをインストールする
pipコマンドでmaterialをインストールする
画面に**(1) Install Mkdocs **を出力する

4. [Mkdocs環境でのHTML生成（ビルド実行）]¶

実行ディレクトリ - プロジェクトが単一の場合：WORK_DIR=./data-store - ※プロジェクトが複数ある場合：WORK_DIR=./data-store/mkdocs

- script: |
    cd $(WORK_DIR)
    ls -lp .
    mkdocs build --clean
    ls -lp .
    ls -lp ./site
  displayName: '** (2)Build Web App $(WORK_DIR) **'

解説
- 修正用リポジトリの作業ディレクトリに移動する
- 作業ディレクトリの中身を確認する
- HTMLを生成する（mkdocs build）
- 作業ディレクトリの中身を表示する
- siteディレクトリ配下に生成したHTMLファイルがあることを表示する
- 画面に** (2)Build Web App $(WORK_DIR) **を表示する

5. [格納先のリポジトリのクローン]¶

公開用リポジトリ　　　　　　　： DEST_REPO_URL ex. https://dev.azure.com/chirin/mkdocs/_git/public-site
公開用リポジトリの対象ブランチ　　： DEST_REPO_BRANCH ex. release_v10
リポジトリ利用のための認証トークン： PAT　（Personal Access Token）

- script: |
    HEADER="Authorization: Basic $(echo -n ":$(PAT)" | base64)"
    git -c http.extraHeader="$HEADER" clone -b $(DEST_REPO_BRANCH)  $(DEST_REPO_URL)
    ls
  displayName: '** (3)clone DEST_REPO_URL: $(DEST_REPO_URL) **'

解説
- HEADER変数にパーソナルアクセストークンをbase64エンコードしたものを設定する
- 公開用リポジトリ（リモート）の対象ブランチ（DEST_REPO_BRANCH）をローカルにクローンする
- クローンしたファイルをlsで表示する
- 画面に(3)clone DEST_REPO_URL: $(DEST_REPO_URL)を表示する

6. [Git情報の確認＆設定]¶

公開用リポジトリ(HTML)と修正用リポジトリ(Md更新)のリポジトリがあるが、そのうち、修正用リポジトリに対してconfigを設定する。

DEST_WORK_DIR : public-site
Build.RequestedFor ：ビルド実行者（組込み変数）
Build.RequestedForEmail ：ビルド実行者のメールアドレス（組込み変数）

- script: |
    cd $(DEST_WORK_DIR)
    # （リモートリポジトリの名前と場所《URL》）を表示する）
    git remote -v
    # 各ブランチの先頭のコミットのIDとメッセージを表示する。
    git branch -v
    git config --local user.name  $(Build.RequestedFor)
    git config --local user.email $(Build.RequestedForEmail)
    git config --local --list | grep 'user.'
  displayName: '** (4)confirm GIT_INFO **'

解説
- 公開用リポジトリの作業ディレクトリ（DEST_WORK_DIR）に移動する。
- 公開用リポジトリの名前と場所を表示する
- 公開用リポジトリのブランチ情報を表示する
- ローカルで実行する名前とメールを設定する
- grepコマンドで設定した内容を表示する
- 画面に** (4)confirm GIT_INFO **を表示する

7. [パイプライン上で生成したHTMLファイル(site配下)を格納先リポジトリにコピーする]¶

生成したHTMLファイルを作業ディレクトリからHTML格納ディレクトリにコピーする。

WORK_DIR_SITE: 修正用リポジトリのHTML作業ディレクトリ-site(HTML格納場所)
プロジェクトが単一の場合 : ./data-store/site
プロジェクトが複数の場合 : ./data-store/mkdocs/site
DEST_REPO_DIR : 公開先リポジトリのHTML格納場所を指定
./public-site/site-1.0/mkdocs　：mkdocsが実際の配置場所
DEST_REPO_NAME : 公開先リポジトリ名
public-site

- script: |
    pwd
    echo "--$(WORK_DIR_SITE)--"
    ls -l $(WORK_DIR_SITE)
    echo "--$(DEST_REPO_DIR)--"
    ls -l $(DEST_REPO_DIR)
    cp -r $(WORK_DIR_SITE) $(DEST_REPO_DIR)
    cd $(DEST_REPO_NAME)
    pwd
    ls
    tree
  displayName: '** (5)cp $(DEST_REPO_DIR) dist **'

解説
- 現在の場所を確認する
- HTML作業用の作業ディレクトリのファイルを表示する
- 公開用リポジトリ（ローカル）のHTML格納ディレクトリのファイルを表示する（何もないことを確認）
- 修正用リポジトリの作業ディレクトリのファイル全てを公開用リポジトリのHTML格納先ディレクトリに再帰的にコピーする
- 公開用リポジトリの親に移動する
- 現在の場所を確認する
- フォルダ・ファイルをツリー表示する
- 画面に** (5)cp $(DEST_REPO_DIR) dist **を表示する

8. [ファイルを公開先リポジトリに格納する]¶

7の手順では、公開先リポジトリ（ローカル）にファイルを格納した。ここの手順では、公開先リポジトリ（ローカル）に格納されたファイルをインデックスに追加し、コミットをした上で、公開先リポジトリ（リモート）に送信（push)する。

- script: |
    cd $(DEST_REPO_NAME)
    echo '---[COMMIT]---'
    git add -A
    NOW_TIME=$(date --iso-8601=seconds)
    COMMIT_MESSAGE="($NOW_TIME)"
    echo "commit-message \"$COMMIT_MESSAGE\""
    git commit -m "$COMMIT_MESSAGE"
    echo '---[DEST_LOG]---'
    git log --oneline -n 3
    echo '---[GIT_PUSH]---'
    # Gitにアクセス可能な共通ユーザのトークンPAT (Personal Access Token)を指定する
    HEADER="Authorization: Basic $(echo -n ":$(PAT)" | base64)"
    echo "git push -v origin $(DEST_REPO_BRANCH)"
    git -c http.extraHeader="$HEADER" push -v origin $(DEST_REPO_BRANCH)
  displayName: '** (6)git COMMIT & PUSH **'

解説
- 公開先リポジトリに移動する
- ファイルをインデックスに追加する（コミットの対象にする）: git add -A
  - Gitで管理していないファイルも含めてインデックスに追加する（ワークツリーから削除したファイルは、削除したことを登録する）
- NOW_TIMEに時間を設定する
- COMMIT_MESSAGEに時間を入れる
- インデックスに追加した変更をリポジトリに記録する：git commit -m
- コミット時のログを表示する
- Gitにアクセス可能な共通ユーザのトークンPAT (Personal Access Token)を指定する
- ローカルリポジトリの変更内容をリモートリポジトリに送信する
- 画面に** (6)git COMMIT & PUSH **を表示する