GitLab Pagesを利用すると、無料でウェブサイトを公開することができます。
GitLab Pagesでは、HTMLで記述したウェブサイトを公開できることに加えて、 Gatsuby/Hugo/Jekyllなどの静的サイトジェネレーターを利用してブログサイトを構築することも簡単にできます。
さらに、独自ドメインを使用することやLet's Encryptを使用して自動的にHTTPS化することも可能です。
動作確認バージョン
以下のバージョンで動作確認をしました。バージョンによっては、動作や表示に違いが発生する場合があるのでご注意ください。
- GitLab Enterprise Edition 13.2.0-pre dfae2aa2b83
GitLab Pagesとは
GitLab Pagesとは、GitLab CI/CDを利用して簡単にウェブサイトを公開できる機能のことです。
この記事ではGitLab CI/CDについての詳しい説明はしませんが、公式ドキュメントが充実しているので、 興味がある方はそちらを参照してください。
テンプレートからプロジェクトを作成する
GitLab Pagesの利用を開始するには、プロジェクトのテンプレートを使用するのが簡単です。 以降では、プロジェクトのテンプレートを使用して、GitLab Pagesを利用する流れを説明します。
はじめに、トップナビの 新規プロジェクト をクリックします。
新規プロジェクト
続いて、プロジェクトの作成方法から テンプレートから作成 を選択します。
プロジェクトの作成方法
利用可能なプロジェクトのテンプレートが表示されます。 Pages/ からはじまるテンプレートがGitLab Pages用のテンプレートです。 今回はシンプルなHTMLのウェブサイトを公開するため、Pages/Plain HTMLの横にあるテンプレートを使用をクリックします。
テンプレートを選択
続いて、新規プロジェクトフォームに必要な情報を入力して プロジェクトを作成 をクリックします。
新規プロジェクトフォーム
| 項目 | 説明 |
|---|---|
| プロジェクト名 | プロジェクト名を入力します。日本語も入力可能です。 |
| Project slug | Project slugはプロジェクトのURLとして使用されます。「半角英数」と「ハイフン(-)」と「アンダースコア_」と「ドット(.)」を使用できます。 |
| プロジェクトの説明 | プロジェクトの説明を入力します。省略可能です。 |
| 可視レベル | 「プライベート」に設定するとプロジェクトメンバーだけがアクセスできます。「パブリック」に設定するとログインなしに誰でもアクセスできます。 |
新規プロジェクトフォームの項目
しばらく待って、次のような画面が表示されたらテンプレートからプロジェクトの作成は成功です。 なお、矢印で指しているpublicフォルダ以下がウェブサイトとして公開され、.gitlab-ci.ymlがGitLab CI/CDの設定ファイルとなります。
作成されたプロジェクトの画面
以上で、テンプレートからプロジェクトの作成は完了です。
パイプラインを実行してウェブサイトを公開する
続いて、.gitlab-ci.ymlの中身を確認してみましょう。
image: alpine:latest
pages:
stage: deploy
script:
- echo 'Nothing to do...'
artifacts:
paths:
- public
only:
- master
.gitlab-ci.yml の項目の説明は次のとおりです。
| 項目 | 値 | 説明 |
|---|---|---|
| image | alpine:latest | ジョブの実行で使用するDockerイメージを指定します。それぞれのジョブはここで指定したDockerイメージから起動したコンテナで実行されます。 |
| pages | pages | ジョブの名前。GitLab Pagesでウェブサイトを公開する際のジョブ名はpagesでなければなりません。 |
| stage | deploy | ジョブを実行するステージを指定します。GitLab CI/CDでは、デフォルトで build -> test -> deploy というステージが定義されています。 |
| script | - echo 'Noting to do...' | ジョブで実行するスクリプトを指定します。publicフォルダ以下のファイルを公開する場合は、スクリプトでの処理は不要ですが、省略することができないので、'Nothing to do…'というメッセージを出力しています。 |
| artifacts.paths | - public | ジョブの成果物を指定します。GitLab Pagesで公開するフォルダはpublicでなければなりません。 |
| only | - master | ジョブを実行するブランチを指定しています。masterブランチにプッシュされた場合のみ、ジョブを実行するように指定しています。 |
.gitlab-ci.yml の項目の説明
通常は、GitLabにプッシュすると自動的にパイプライン(GitLabでのCI/CDの別名)が実行されますが、プロジェクトを作成しただけでは実行されません。 今回は、ウェブサイトを公開するために手動でパイプラインを実行してみましょう。 そのためにはまず、サイドメニューのCI/CD > パイプラインをクリックしたあとに、画面右上のパイプライン実行をクリックします。
パイプラインを実行
すると、パイプラインを実行するブランチを選択し、変数を入力する画面が表示されます。 今回は特に変更する必要はないので、そのままパイプラインを実行をクリックします。
パイプラインを実行するブランチの選択と変数の入力
パイプラインの実行が開始されるので、完了するまでしばらく待ちます。 パイプラインが完了すると次のような画面が表示されるはずです。
パイプラインの完了画面
パイプラインが完了してからしばらく待つとウェブサイトが公開されます。 早速、ウェブサイトを表示してみましょう。
そのためにはまず、サイドメニューの設定 > Pagesをクリックします。続いて、ページヘアクセスに表示されているURLをクリックします。
Pagesの設定画面
すると、次のようなウェブサイトが表示されるはずです。 もしも、表示されない場合はしばらく待ってからもう一度アクセスしてみてください。
ウェブサイトを表示
以上で、パイプラインを実行してウェブサイトを公開する作業は完了です。
独自ドメインを設定する
GitLab Pagesで公開するウェブサイトのURLには、次のようなルールがあります。 なお、{xxx}のように表記している箇所はプレースホルダーを表しています。
| GitLab Pages のタイプ | GitLab に作成したProject slug | ウェブサイトの URL |
|---|---|---|
| ユーザーページ | {ユーザー名}.gitlab.io | http(s)://{ユーザー名}.gitlab.io |
| グループページ | {グループ名}.gitlab.io | http(s)://{グループ名}.gitlab.io |
| ユーザー配下のプロジェクトページ | {プロジェクト名} | http(s)://{ユーザー名}.gitlab.io/{プロジェクト名} |
| グループ配下のプロジェクトページ | {プロジェクト名} | http(s)://{グループ名}.gitlab.io/{プロジェクト名} |
しかし、自分のホームページやブログを独自ドメインで公開したい場合があると思います。 そのような場合は、GitLab Pagesの設定でドメインを追加することで解決できます。
ドメインを追加するには、サイドメニューの設定 > Pagesをクリックして表示される画面の右上の新ドメイン をクリックします。
ドメインを追加
新しいドメインの入力フォームが表示されるので、必要な情報を入力して新しいドメインを作成をクリックします。
新しいドメインの入力フォームフォーム
| 項目 | 説明 |
|---|---|
| ドメイン | ドメインを入力します。設定するドメインは各自で事前に購入してください。 |
| Let's Encryptを用いて自動的に証明書を管理 | 基本的にオンから変更しないでください。 |
ドメインを追加すると、次のような画面が表示されるはずです。 この画面に表示されているCNAMEレコードとTXTレコードを、あなたが利用しているDNSサーバーに登録してください。
追加されたドメイン
DNSサーバーへのレコードの登録が完了したら画面の未検証の横のアイコンをクリックして、 次のように検証済みと表示されることを確認してください。
ドメインの所有者を確認
それでは、追加したドメインでウェブサイトにアクセスしてみましょう。
Let's EncryptでSSL証明書が発行されるにはしばらく時間がかかります。 もしも、SSL証明書のエラーが発生する場合は、しばらく待ってからもう一度アクセスしてみてください。
以上で、独自ドメインの設定は完了です。
トラブルシューティング
GitLab Pagesを使用していて発生する問題への対応方法を説明します。
ローカル環境では正しく表示されるのに、GitLab Pagesだと表示が崩れる
GitLab Pagesで公開されるウェブサイトのURLは http(s)://{ユーザー名}.gitlab.io/{プロジェクト名} のように、プロジェクト別にサブディレクトリで分けて公開されます。
そのため、CSSやJavaScriptや画像ファイルを絶対パスで指定していると読み込めない場合があります。
そのような場合は、相対パスで指定することで解決する場合があります。
SSL証明書のエラーが発生する
ユーザー名やグループ名に「ドット(.)」が含まれていると、SSL証明書のエラーが発生します。
例えば、ユーザー名が taro.yamada のユーザーが GitLab Pages でユーザーページを公開すると、 ウェブサイトの URL は http(s)://taro.yamada.gitlab.io となります。
一方、GitLab.com の GitLab Pages では、Common Name が *.gitlab.io のワイルドカード SSL 証明書が使用されています。 これは taro.yamada.gitlab.io というドメインでは無効な SSL サーバー証明書になります。
注: taro.yamada.gitlab.io で有効な Common Name は taro.yamada.gitlab.io か *.yamada.gitlab.io のどちらかになります。
そのような場合は、「ドット(.)」を含まないグループ名で新しいグループを作成し、 プロジェクトをそのグループ配下へ移動することでSSL証明書のエラーを回避することができます。
まとめ
この記事では、GitLab Pagesを使用してHTMLで作成したシンプルなウェブサイトを公開する手順を説明しました。
あとは、リポジトリをローカルにクローンして、変更をコミットしてからプッシュするだけで、自動的にウェブサイトが更新されます。
また、この記事で使用しませんでしたが、標準でGatsby/Hugo/Jekyll/GitBook/Middlemanのテンプレートも用意されているので、 それらの静的サイトジェネレーターを使用してウェブサイトを公開することも簡単にできます。
もちろん、標準のテンプレートに存在しない静的サイトジェネレーターについても、.gitlab-ci.ymlにビルド用スクリプトを記述することで、 比較的簡単に利用することができます。 GitLab Pages exampleグループでは、様々な静的サイトジェネレーターのサンプルプロジェクトが公開されているので、 ぜひそちらも参考にしてください。
カバーイメージの提供: Anne Nygård on Unsplash
