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によって自動的にビルドされますが、すべてのツールイメージをローカルでビルドし、タグ付けすることができます:
- Dockerがインストールされていることを確認してください。
-
gitlab-docs
リポジトリのdockerfiles/
ディレクトリにいることを確認してください。 -
イメージを構築します:
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製品とは異なるバージョン番号を使っているので、バージョンマッピングを追加する必要があります:
- 新しいチャートバージョンの安定版ブランチが作成されていることを確認してください。 もしわからない場合や見つからない場合は、
#g_delivery
チャンネルに連絡してください。 -
gitlab-docs
リポジトリのルートパスにいることを確認してください。 -
content/_data/chart_versions.yaml
を開き、バージョンマッピングを使って新しい安定版ブランチのバージョンを追加します。必要なのはmajor.minor
バージョンだけです。 - 新しいマージリクエストを作成し、マージしてください。
2. 単一バージョンのイメージの作成
単一のdocsバージョンはリリースマージリクエストの前に作成する必要がありますが、これはすべての製品の安定ブランチが作成されたときに行う必要があります。
-
gitlab-docs
リポジトリのルートパスにいることを確認してください。 -
Rakeタスクを実行して単一バージョンを作成します:
./bin/rake "release:single[12.0]"
新しい
Dockerfile.12.0
が作成され、.gitlab-ci.yml
ブランチの変数が新しいブランチに更新されているはずです。これらは自動的にコミットされます。 - 新しく作成したブランチをプッシュしますが、マージリクエストは作成しないでください。 プッシュすると、
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. リリース・マージ・リクエストの作成
さて、新しいバージョンを追加し、古いバージョンをローテーションする月例リリースのマージリクエストを作成する時が来ました:
-
gitlab-docs
リポジトリのルートパスにいることを確認してください。 -
ブランチの作成
release-X-Y
:git checkout master git checkout -b release-12-0
-
オンライン版とオフライン版のローテーション
上流のマスターブランチ(GitLab.comのドキュメント)から取得したものと、最新の安定版3つです。
content/_data/versions.yaml
を編集し、新しい変更を反映させるためにバージョンを回転させます:-
online
最新の3つの安定版。 -
offline
オフラインアーカイブとして提供される以前のすべてのバージョン。
-
-
:latest
と Docker イメージを更新します::archives
以下の2つのDockerfileを更新する必要があります:
-
dockerfiles/Dockerfile.archives
- 最新バージョンをリストの一番上に追加します。 -
Dockerfile.master
- バージョンをローテーションします(古いものは削除され、最新のものがリストの一番上に追加されます)。
-
-
最終的に、変更されたファイルは全部で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
の内容は、すべてのオンライン版で変更する必要があります:
-
ドロップダウンの更新に必要なマージリクエストを作成し、パイプラインが成功したときに自動的にマージされるように設定する Rake タスクを実行します。
release-X-Y
ブランチがローカルに存在し、それに切り替えている必要があります。そうでない場合、Rake タスクは失敗します:./bin/rake release:dropdowns
-
マージリクエストページにアクセスしてパイプラインがパスしていることを確認し、すべてがマージされたら、次の最後のステップに進みます。
5. リリースマージリクエストのマージ
ドロップダウンしたマージリクエストがそれぞれのバージョン (安定版ブランチ) にマージされ、別のパイプラインが起動するはずです。 この時点では、パイプラインを子守して失敗しないようにするだけです:
- パイプラインページ
https://gitlab.com/gitlab-org/gitlab-docs/pipelines
をチェックし、すべての安定版ブランチに緑のパイプラインがあることを確認してください。 - オンラインバージョンのパイプラインがすべて成功したら、リリースのマージリクエストをマージします。
- 最後に、
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はパスするはずです。