とあるチームのメンテナンス手順書の管理の話

TL;DR

  • 世の中には「メンテナンス手順書」って言うやつがあるよ
  • とあるチームでは GitLab を使って 「メンテナンス手順書」を管理しているよ
  • 個人的には GitLab を使ったメンテナンス手順書の管理は便利だと思うよ

はじめに

こんにちは。短い育児休業が終わり会社に復帰しました。 妻が継続で育休を取ってくれているおかげで、何とか仕事も進められています。ありがたい事です。 また、会社復帰に際してもスムーズに業務に戻れるよういろいろと配慮いただいたチームの皆様にも感謝です。ありがとうございます。

会社復帰して仕事を進める中での気づきのまとめとして、本稿ではとあるチームで行われているメンテナンス手順書の管理の方法をご紹介します。

「メンテナンス手順書」 とは？

ご存知の通り、ITシステムには「運用」というやつが多少を問わず必ずあります。
「運用」というやつには、「保守」や「メンテナンス」と言われる作業（以下「メンテナンス作業」）が多少を問わず存在します。
これは一般的にはシステムに変更を加えるものであり、軽重はあるもののリスクを伴うものとなっています。

多くの「運用チーム」ではメンテナンス作業のリスクをマネジメントするために、メンテナンス作業に際して「手順書」を作成し、
複数名のレビュー・確認や承認を経て作業を実施するような運用を行っているのではないかと思います。

本稿における「メンテナンス手順書」はそのようなメンテナンス作業のための手順書の事を指すものとします。

とあるチームの「メンテナンス手順書」に求められる事

「メンテナンス手順書」と言った時にイメージされるものは、IT業界に身を置く人の中でも職種や業種によって異なるのではないでしょうか。 本稿で紹介する「とあるチーム」は、クラウドサービスを活用してITシステムを自ら開発・運用しているチームを想定します。

メンテナンスの立案・手順作成・レビュー・リハーサル・承認・実施をすべてチーム内＋チームが属する組織の管理職で行っています。

注意：環境が異なるチーム（例えばメンテナンス手順書を作成するチームと実施するチームが異なるような場合）では、「とあるチーム」に求められる以外の要件が沢山ある場合もあるでしょう。

この「とあるチーム」のメンテナンス手順書には以下のようなものが含まれます。

  • メンテナンスの概要
    • 目的や変更要旨
  • メンテナンス日時
  • メンテナンス手順の実績
    • 過去実績や検証結果
  • メンテナンス手順
    • メンテナンスの前提条件
    • 実施手順
      • 事後手順や切り戻し手順も含む
  • 上記内容が管理職のレビューを経て承認されている事

「メンテナンス手順書の管理」に求められること

メンテナンス手順書のライフサイクル

とあるチームでは、先述の「メンテナンス手順書」は以下のようなライフサイクルをたどります。（2,3 は前後・繰り返しの場合もある）

  1. 作成
  2. リハーサル・修正
  3. レビュー・修正
  4. 承認
  5. 実施

多くのIT組織において、各ステップの軽重・前後はあれど似たようなステップをたどるのではないかと思います。

それぞれのステップに求められる管理の要件は以下のようなものです。

「1. 作成」の管理要件

このステップでは特に求められている管理の要件はありません。 強いて言うならば、作成という作業そのものがやりやすい事が求められるでしょう。

「2. リハーサル・修正」の管理要件

このステップでは、手順書に起こした変更手順を開発環境や検証環境に適用し、本番メンテナンスのリハーサルを行います。

Tips：本番環境とリハーサルに用いる環境で何らかの差分がある場合（原則差分が無いことが望ましいが現実は難しい）はその差分に留意してリハーサルを行いましょう。

リハーサルの結果を次のステップ（3.レビュー）で参照できるように記録しておく必要があります。 また、リハーサルの最中に手順に間違いや不足が見つかった場合には、1のステップで作成した手順を修正する必要があります。 リハーサルにあたっては手順の見やすさ、修正に際しては修正作業のしやすさが求められます。

「3. レビュー・修正」の管理要件

このステップでは、メンバーや管理職にメンテナンス手順をレビューしてもらい、必要に応じて指摘・修正のキャッチボールが行われます。 レビュー・修正のしやすさ、改変内容の分かりやすさが求められます。 レビュワーにとっては、メンテナンス手順が見やすく表示され、気になった個所に簡単に指摘や質問のコメントを入れることが出来ると良いでしょう。 修正側にとっては、指摘の場所と内容が分かりやすいと修正がしやすいでしょう。 また、指摘に対してどのように修正を加えたのかが明確に分かると再レビューもしやすいでしょう。

「4. 承認」の管理要件

  1. レビュー・修正 の手順で指摘事項をすべてクリアした手順を最終的に管理職が承認します。これによってメンテナンスの実施に進むことができます。 このステップでは、承認の証跡が明示できることが求められます。 組織によっては、承認者が何名も居て順番に承認を貰う事が求められることもあるでしょう。 また、管理職でないチームメンバーも承認フローに加わる事もあるでしょう。

「5. 実施」の管理要件

このステップでは、実際にメンテナンスを実施します。 全てのレビューが完了し、管理職による承認が通った手順だけがメンテナンスに進むことが出来るので、レビューと承認が完了している事が明確に分かる事が求められます。 また、メンテナンスの実施に際しては作業の記録を残すことも必須となる事が多いでしょう。

組織によってはメンテナンス実施の記録を管理職に共有し、承認を貰う場合もあるかもしれません。 その場合は承認証跡を残しやすいことも求められるでしょう。

「とあるチーム」での実現方法

このように様々な要件のある「メンテナンス手順書の管理」を、とあるチームでは「GitLab」を使って実施しています。

GitLab はバージョン管理システムである Git のレポジトリマネージャーとして動作するWEBアプリケーションであり、 Gitレポジトリとしての動作だけでなく、イシューやマージリクエスト、Wiki等の様々な機能を搭載しています。

とあるチームでは、メンテナンス手順書を GitLab のレポジトリ機能に格納し管理しています。 それぞれのステップでどのような機能を使っているのか紹介します。

GitLab を使ったメンテナンス手順書の「1. 作成」

メンテナンスの計画が立ち上がったら、まずは GitLab に「メンテナンス手順作成」をイシュー化します。

GitLabのメンテナンス手順書を管理しているレポジトリに新しい手順を記載するブランチ（一時的な作業場）を作成します。

Tips : この時、GitLab のイシューから「マージリクエスト」を作成する機能を利用すると便利です。レポジトリをクローンしてお好みのGitツールで操作することもできます。

新しいブランチが出来たら、その中でテキストファイルを作成します。

Tips : この時、マージリクエスト画面から WebIDE を呼び出して作業をすると便利です。もちろん、レポジトリをクローンしてお好みのエディタで編集することもできます。どちらにせよこまめに編集をコミットすることで突発的なトラブルに備えましょう。

とあるチームでは、 Markdown ※1 記法を用いてメンテナンス手順書をテキストファイルとして作成します。 Markdown で記述することで、文書として書きやすく読みやすい形式を実現しています。

※1. Markdown は文章を「書きやすくて読みやすいプレーンテキスト」として記述するためのルールとして利用でき、さらに各種ソフトウェアによってさらに見やすい表示に変換する事の出来る記法です。

Tips : GitLab では Markdown でチェックボックス付きのリストを簡単に記述する事ができます。

- [ ] 手順1
- [ ] 手順2

例えば、上記 Markdown が以下のように表現されます。

  • 手順1
  • 手順2

チェックボックスにチェックしながら進めることが可能な手順書が簡単に作成でき、リハーサルや実施時に手順を飛ばしたり2度同じ手順を実施するリスクを軽減できます。

GitLab を使ったメンテナンス手順書の「2. リハーサル・修正」

Markdown で作成した手順を先に作成したイシューの本文やコメントに張り付けると、Markdown が少し見やすい形に表現されます。 「リハーサル実施」用のイシューを作って実施しても良いでしょう。 チェックボックス記法を活用した手順書であれば、手順飛ばしや2重実行のリスクを減らして手順のリハーサルを行う事ができます。

リハーサルで手順の不足や誤りが見つかった場合は、前述の Web IDE やお好みのエディタ等を使って修正を行い、リハーサルの実施内容や実施結果をイシューのコメントとして記録します。

GitLab を使ったメンテナンス手順書の「3. レビュー・修正」

作成者が問題の無い手順書が出来たと思ったら、GitLab の「マージリクエスト」を使ってレビューをしてもらいます。 「マージリクエスト」では、新規作成されたメンテナンス手順が全て Markdown 記法のままで表示され、レビュワーは気になった個所があれば各行に対してコメントを入れる機能を使って指摘します。

Tips: この時、簡単な入力ミスの修正提案は suggestion 機能を使うと便利です。

作成者は指摘の内容とその行を確認し、必要に応じてコメント返答や内容の修正を行います。 内容の修正はGitの機能によって改版として修正前後が分かる状態で記録されるため、どのように修正したのかレビュワーが確認することができます。

Tips: この時もマージリクエスト画面から WebIDE を呼び出して作業をすると便利です。レポジトリをクローンしてお好みのエディタで編集することも（ry

GitLab を使ったメンテナンス手順書の「4. 承認」

全ての指摘事項がクリアになったら、レビュワーはGitLabのマージリクエストを「承認」します。 マージリクエストには承認日時や承認者の情報が記録されます。

Tips: メンテナンス手順書を管理するレポジトリの「承認ルール」の活用を検討しましょう。管理職による「承認」の必須化やチームメンバー N人以上の「承認」必須等のルール付けが可能です。

GitLab を使ったメンテナンス手順書の「5. 実施」

メンテナンス手順書のマージリクエストが管理職によって承認されたら、いよいよメンテナンスを実施します。 レビューと承認が完了している事を確認し、マージリクエストを「マージ」します。 「承認ルール」が設定されている場合、必要な承認者全員に承認されていないとマージする事が出来ません。

「メンテナンス実施イシュー」を作成し、マージされた手順を本文に張り付け、メンテナンスを開始します。 メンテナンス手順の指示通りに作業を進め、必要に応じて作業のログや結果をイシューにコメントすることで記録を残します。

Tips: やはりチェックボックス記法を活用した手順書が便利です。

万が一トラブルが発生した場合は、必要な対処を行うと共に、イシューのコメントに記録を付けます。

最後まで問題なく手順を実施できた場合は、作業記録に不足が無いことを確認してイシューをクローズします。

メンテナンス実施に関わる全ての記録をイシューにまとめることで、後々に振り返る際や監査等第3者に情報を提供する必要が発生した場合でも必要な情報に素早くアクセスすることができます。

また、承認された「メンテナンス手順書」はメンテナンス手順書管理のレポジトリに格納されるため、
次のメンテナンス手順書作成の際に参照することが容易になります。

終わりに

以上が、「とあるチーム」で行われている「メンテナンス手順書の管理」手法です。

お気づきの通り、数々のメンテナンス手順書の管理要件をGitLabの機能の中で頑張って補っているので、メンバーの性善説に基づいた運用も多くあります。 改善点はまだまだあるかとは思いますが、一般的に多く用いられている他の方法と比べても同等かそれ以上の運用性を実現できているのではないかなと個人的には評価しています。

GitLab には イシューや Wiki 等、メンテナンス手順書を管理できそうな機能が他にもあますが、メンテナンス手順書作成に際してはレビューと修正のやり取りを円滑に行えるマージリクエストが便利に感じていて、それを生かせるレポジトリを使った管理方法が気に入っています。 また、マージリクエストの suggestion 機能による「修正提案」はレビュワーが一方的に指摘するだけにならない仕組みで、レビュワーと作成者が相互にコラボレーションする事の出来るお気に入りの機能の1つです。

パッと思いつくこの方法のデメリットは、画像を挿入しづらい事です。GitLabのWikiやイシュー機能であれば ドラッグ&ドロップ で画像を挿入し展開表示することが可能ですが、
レポジトリ管理の場合はファイルとしてレポジトリに格納した上でパスを指定して Markdown に記載する必要があります。
そのためか、とあるチームではCLIベースでの手順化や自動化のモチベーションが高く、画像を極力使わなくて済むようにしているように感じます。

メリット・デメリット双方あるかとは思いますが、GitLab の Git レポジトリの機能を使ってメンテナンス手順書を管理している事例はあまり無いように感じたので紹介してみました。

もちろん上記に紹介した内容のほとんどは GitHub など他のGitレポジトリマネージャーソフトウェアで実現できると思うので、参考にして頂ければ幸いです。