GitLab Docsの月次リリースプロセス

dockerfiles ディレクトリには、バージョン管理されたウェブサイトをビルドしてデプロイするために必要なDockerfileがすべて含まれています。 これはDockerのDockerfileに大きくインスパイアされています。

以下のDockerfileが使用されています。

ドッカーファイル docker イメージ 説明
Dockerfile.bootstrap gitlab-docs:bootstrap ウェブサイトを構築するために必要なすべての依存関係がコンテナに含まれています。gemsが更新され、Gemfile{,.lock} が変更された場合、イメージを再構築する必要があります。
Dockerfile.builder.onbuild gitlab-docs:builder-onbuild docs ウェブサイトを構築するためのベースイメージ。ONBUILD を使ってすべてのステップを実行し、gitlab-docs:bootstrapに依存しています。
Dockerfile.nginx.onbuild gitlab-docs:nginx-onbuild ONBUILD を使ってアーカイブをコピーするために必要なすべてのステップを実行し、単一のドキュメントアーカイブを構築するときに呼び出される親Dockerfile.builder.onbuild に依存します (各ブランチのDockerfile を参照してください)。
Dockerfile.archives gitlab-docs:archives ウェブサイトの全バージョンを1つのアーカイブにコンテナし、各バージョンの生成されたHTMLファイルを1つの場所にコピーします。

画像の作り方

ビルドイメージはGitLab CI/CDによって自動的にビルドされますが、すべてのツールイメージをローカルでビルドし、タグ付けすることができます：

  1. Dockerがインストールされていることを確認してください。
  2. gitlab-docs リポジトリのdockerfiles/ ディレクトリにいることを確認してください。

  3. イメージを構築します： 

    docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:bootstrap -f Dockerfile.bootstrap ../
docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:builder-onbuild -f Dockerfile.builder.onbuild ../
docker build -t registry.gitlab.com/gitlab-org/gitlab-docs:nginx-onbuild -f Dockerfile.nginx.onbuild ../

それぞれの画像について、.gitlab-ci.yml のimages ステージの下に手動ジョブがあり、自由に呼び出すことができます。

毎月のリリースプロセス

22日にGitLabの新しいバージョンがリリースされたら、それぞれのシングルDockerイメージを作成し、ドロップダウンが正しく動作するようにいくつかのファイルを更新する必要があります。

1. Chartバージョンの追加

Chartは他のGitLab製品とは異なるバージョン番号を使っているので、バージョンマッピングを追加する必要があります：

  1. 新しいチャートバージョンの安定版ブランチが作成されていることを確認してください。 もしわからない場合や見つからない場合は、#g_delivery チャンネルに連絡してください。
  2. gitlab-docs リポジトリのルートパスにいることを確認してください。
  3. content/_data/chart_versions.yaml を開き、バージョンマッピングを使って新しい安定版ブランチのバージョンを追加します。必要なのはmajor.minor バージョンだけです。
  4. 新しいマージリクエストを作成し、マージしてください。
ヒント:将来のマッピングを作成しておくと便利です。 GitLabの新しいバージョンがリリースされたときに、この最初のステップを繰り返す必要がなくなります。

2. 単一バージョンのイメージの作成

単一のdocsバージョンはリリースマージリクエストの前に作成する必要がありますが、これはすべての製品の安定ブランチが作成されたときに行う必要があります。

  1. gitlab-docs リポジトリのルートパスにいることを確認してください。

  2. Rakeタスクを実行して単一バージョンを作成します： 

    ./bin/rake "release:single[12.0]"

    新しいDockerfile.12.0 が作成され、.gitlab-ci.yml ブランチの変数が新しいブランチに更新されているはずです。これらは自動的にコミットされます。

  3. 新しく作成したブランチをプッシュしますが、マージリクエストは作成しないでください。 プッシュすると、image:docker-singe ジョブが最初のステップで作成したブランチ名でタグ付けされた新しい Docker イメージを作成します。最終的に、イメージはコンテナレジストリにアップロードされ、https://gitlab.com/gitlab-org/gitlab-docs/-/environments/folders/registry のregistry 環境フォルダの下にリストされます (開発者アクセス権が必要です)。

オプションで、イメージをビルドして実行することで、ローカルでテストすることもできます： 

docker build -t docs:12.0 -f Dockerfile.12.0 .
docker run -it --rm -p 4000:4000 docs:12.0

http://localhost:4000/12.0/ にアクセスして、すべてが正しく機能しているかどうかを確認してください。

3. リリース・マージ・リクエストの作成

注：自動化予定。

さて、新しいバージョンを追加し、古いバージョンをローテーションする月例リリースのマージリクエストを作成する時が来ました：

  1. gitlab-docs リポジトリのルートパスにいることを確認してください。

  2. ブランチの作成release-X-Y： 

    git checkout master
git checkout -b release-12-0

  3. オンライン版とオフライン版のローテーション

    上流のマスターブランチ（GitLab.comのドキュメント）から取得したものと、最新の安定版3つです。

    content/_data/versions.yaml を編集し、新しい変更を反映させるためにバージョンを回転させます：

    • online最新の3つの安定版。
    • offlineオフラインアーカイブとして提供される以前のすべてのバージョン。

  4. :latest と Docker イメージを更新します：:archives

    以下の2つのDockerfileを更新する必要があります：

    1. dockerfiles/Dockerfile.archives - 最新バージョンをリストの一番上に追加します。
    2. Dockerfile.master - バージョンをローテーションします（古いものは削除され、最新のものがリストの一番上に追加されます）。

  5. 最終的に、変更されたファイルは全部で4つになるはずです。 コミットしてプッシュすると、”Release “テンプレートを使ってマージリクエストが作成されます： 

    git add content/ Dockerfile.master dockerfiles/Dockerfile.archives
git commit -m "Release 12.0"
git push origin release-12-0

4. すべてのオンラインバージョンのドロップダウンを更新

バージョンのドロップダウンは、ある意味で「ハードコード」されています。 サイトがビルドされるときに、content/_data/versions.yaml の内容を見て、それに基づいてドロップダウンに入力されます。 そのため、古いブランチでは内容が異なり、ドロップダウンには一つ以上のリリースが遅れて表示されます。ドロップダウンの新しい変更は、マージされていないrelease-X-Y ブランチに含まれていることを覚えておいてください。

content/_data/versions.yaml の内容は、すべてのオンライン版で変更する必要があります：

  1. ドロップダウンの更新に必要なマージリクエストを作成し、パイプラインが成功したときに自動的にマージされるように設定する Rake タスクを実行します。release-X-Y ブランチがローカルに存在し、それに切り替えている必要があります。そうでない場合、Rake タスクは失敗します： 

    ./bin/rake release:dropdowns

  2. マージリクエストページにアクセスしてパイプラインがパスしていることを確認し、すべてがマージされたら、次の最後のステップに進みます。

ヒント:パイプラインが失敗した場合は、トラブルシューティングを参照してください。

5. リリースマージリクエストのマージ

ドロップダウンしたマージリクエストがそれぞれのバージョン (安定版ブランチ) にマージされ、別のパイプラインが起動するはずです。 この時点では、パイプラインを子守して失敗しないようにするだけです：

  1. パイプラインページhttps://gitlab.com/gitlab-org/gitlab-docs/pipelinesをチェックし、すべての安定版ブランチに緑のパイプラインがあることを確認してください。
  2. オンラインバージョンのパイプラインがすべて成功したら、リリースのマージリクエストをマージします。
  3. 最後に、https://gitlab.com/gitlab-org/gitlab-docs/pipeline_schedules からBuild docker images weekly パイプラインを実行し、:latest と:archives Docker イメージをビルドします。

スケジュールされたパイプラインが成功すると、docsサイトはすべての新しいバージョンでオンラインにデプロイされます。

古いDockerイメージを新しいアップストリームドキュメントコンテンツで更新します。

単一のDockerイメージに含まれていない製品の安定版ブランチに変更があった場合は、該当するバージョンのパイプライン(https://gitlab.com/gitlab-org/gitlab-docs/pipelines/new)を再実行するだけです。

新しいウェブサイトの変更を古いバージョンに移植

警告:ウェブサイトのバックエンドを常に変更しているため、古いブランチへの変更を移植すると、意図しない影響が出る可能性があります。 自分が何をしているのかわかっている場合にのみ使用し、必ずローカルでテストしてください。

ウェブサイトは変化し続け、改善され続けます。 それらの変更を安定版ブランチに統合するためには、時々特定の変更を選ぶ必要があります。

これが不可能な場合や変更が多い場合は、マスターをマージしてください： 

git branch 12.0
git fetch origin master
git merge origin/master

トラブルシューティング

新バージョンのリリースは、多くの可動部分を含む長いプロセスです。

test_internal_links_and_anchors ドロップダウンでのマージリクエストの失敗

注意:現在では、それぞれのブランチの.gitlab-ci.yml にバージョンを固定するようになりましたので、以下の手順は非推奨です。

安定版のドロップダウンを更新する際、いくつかのリンクが失敗するケースがあるかもしれません。 ドロップダウンのMRが作成されるプロセスには注意点があり、それは、テストはそれぞれの安定版ではなく、すべての製品のマスターブランチをプルして実行されるということです。

実際のシナリオでは、12.2のドロップダウンを12.4のマージリクエストに合わせるためのアップデートは、test_internal_links_and_anchors テストのために失敗しました。

これは、製品の名前が変更され（gitlab-monitor からgitlab-exporter）、12.2 のドキュメントで古い名前が参照されていたためです。12.2 のそれぞれの安定版ブランチが使用されていれば、失敗することはなかったのですが、compile_dev のジョブ、master のブランチがプルされたことがわかります。

これを修正するには、update-12-2-for-release-12-4 ブランチのパイプライン (https://gitlab.com/gitlab-org/gitlab-docs/pipelines/new) を、以下の環境変数を含めて再実行します：

  • BRANCH_CE に設定します。12-2-stable
  • BRANCH_EE に設定します。12-2-stable-ee
  • BRANCH_OMNIBUS に設定します。12-2-stable
  • BRANCH_RUNNER に設定します。12-2-stable
  • BRANCH_CHARTS に設定します。2-2-stable

これでMRはパスするはずです。