正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

チュートリアル: GitLabでHugoサイトをビルド、テスト、デプロイする

このチュートリアルでは、HugoサイトをCI/CDパイプラインでビルド、テスト、デプロイする手順を説明します。

チュートリアルの終わりまでに、動作するパイプラインとGitLab PagesにデプロイされたHugoサイトが完成します。

実施する作業の概要を次に示します:

  1. Hugoサイトを準備する。
  2. GitLabプロジェクトを作成する。
  3. HugoサイトをGitLabにプッシュする。
  4. CI/CDパイプラインでHugoサイトをビルドする。
  5. GitLab PagesでHugoサイトをデプロイする。

はじめる前

  • GitLab.comのアカウント。
  • Gitに関する知識。
  • Hugoサイト（まだお持ちでない場合は、Hugo Quick Startの手順に従ってください）。

Hugoサイトを準備する

まず、HugoサイトがGitLabにプッシュする準備ができていることを確認してください。コンテンツ、テーマ、Hugoの設定ファイルが必要です。

GitLabがビルドするため、サイトをビルドする必要はありません。実際、publicフォルダーをアップロードしないことが重要です。後で競合が発生する可能性があります。

publicフォルダーを除外する最も簡単な方法は、.gitignoreファイルを作成し、public/というテキストの新しい行を追加することです。

これを行うには、Hugoプロジェクトの最上位で次のコマンドを実行します:

echo "public/" >> .gitignore

これにより、public/が新しい.gitignoreファイルに追加されるか、既存のファイルに追記されます。

Hugoサイトは、GitLabプロジェクトを作成したら、プッシュする準備ができています。

GitLabプロジェクトを作成する

まだ作成していない場合は、Hugoサイト用の空のGitLabプロジェクトを作成してください。

GitLabで空のプロジェクトを作成するには:

  1. 右上隅で、新規作成（ plus ）と新規プロジェクト/リポジトリを選択します。
  2. 空のプロジェクトの作成を選択します。
  3. プロジェクトの詳細を入力します。
    • プロジェクト名フィールドに、プロジェクトの名前を入力します。名前は、小文字または大文字（a-zA-Z）、数字（0-9）、絵文字、またはアンダースコア（_）で始まる必要があります。ドット（.）、プラス記号（+）、ダッシュ（-）、またはスペースも使用できます。
    • プロジェクトslugフィールドに、プロジェクトへのパスを入力します。GitLabインスタンスは、このslugをプロジェクトへのURLパスとして使用します。slugを変更するには、最初にプロジェクト名を入力し、次にslugを変更します。
    • 表示レベルは非公開または公開のいずれかに設定できます。非公開を選択してもウェブサイトは公開されますが、コードは非公開のままになります。
    • 既存のリポジトリをプッシュするため、リポジトリを初期化しREADMEファイルを生成するのチェックボックスをオフにします。
  4. 準備ができたら、プロジェクトを作成を選択します。
  5. この新しいプロジェクトにコードをプッシュするための手順が表示されるはずです。次のステップでそれらの手順が必要になります。

これでHugoサイトの場所ができました！

HugoサイトをGitLabにプッシュする

次に、ローカルのHugoサイトをリモートのGitLabプロジェクトにプッシュする必要があります。

前のステップで新しいGitLabプロジェクトを作成した場合、リポジトリを初期化し、ファイルをコミットしてプッシュするための手順が表示されます。

それ以外の場合は、ローカルGitリポジトリのリモートoriginが、あなたのGitLabプロジェクトと一致していることを確認してください。

デフォルトブランチがmainであると仮定して、次のコマンドでHugoサイトをプッシュすることができます:

git push origin main

サイトをプッシュした後、publicフォルダーを除くすべてのコンテンツが表示されるはずです。publicフォルダーは.gitignoreファイルによって除外されました。

次のステップでは、CI/CDパイプラインを使用してサイトをビルドし、そのpublicフォルダーを再作成します。

CI/CDパイプラインでHugoサイトをビルドする

GitLabでHugoサイトをビルドするには、まずCI/CDパイプラインの指示を指定するための.gitlab-ci.ymlファイルを作成する必要があります。これを以前に行ったことがない場合は、大変に思えるかもしれません。ただし、GitLabが必要なすべてを提供します。

以下に示す.gitlab-ci.ymlファイルを使用するには、hugo.tomlファイルも一致するテーマパスを示していることを確認してください。以下の例のhugo.tomlファイルは、GitLab PagesプロジェクトのbaseURL設定も示しています。

baseURL = 'https://<your-namespace>.gitlab.io/<project-path>'
languageCode = 'en-us'
title = 'Hugo on GitLab'
[module]
[[module.imports]]
  path = 'github.com/adityatelange/hugo-PaperMod'

GitLabの設定オプションを追加する

設定オプションは、.gitlab-ci.ymlという特別なファイルで指定します。

Hugoテンプレートを使用して.gitlab-ci.ymlファイルを作成するには:

  1. 左側のサイドバーで、コード > リポジトリを選択します。
  2. ファイルリストの上にあるプラスアイコン ( + ) を選択し、ドロップダウンリストから新しいファイルを選択します。
  3. ファイル名には.gitlab-ci.ymlと入力します。先頭のピリオドを省略しないでください。
  4. テンプレートを適用ドロップダウンリストを選択し、フィルターボックスに「Hugo」と入力します。
  5. 結果のHugoを選択すると、CI/CDを使用してHugoサイトをビルドするために必要なすべてのコードでファイルが入力された状態になります。

この.gitlab-ci.ymlファイルで何が起こっているのか、詳しく見てみましょう。

default:
  image: "hugomods/hugo:exts"

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  THEME_URL: "github.com/adityatelange/hugo-PaperMod"

test:  # builds and tests your site
  script:
    - hugo
  rules:
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

create-pages:  # a user-defined job that builds your pages and saves them to the specified path.
  script:
    - hugo
  pages: true  # specifies that this is a Pages job
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  environment: production
  • imageは、Hugoを含むGitLabのレジストリからのイメージを指定します。このイメージは、サイトがビルドされる環境を作成するために使用されます。
  • GIT_SUBMODULE_STRATEGY変数は、GitLabがGitサブモジュールも参照するようにします。これはHugoテーマで時々使用されます。
  • testは、Hugoサイトがデプロイされる前にテストを実行できるジョブです。テストジョブは、デフォルトブランチへの変更をコミットする場合を除き、すべての場合に実行されます。コマンドはscriptの下に配置します。このジョブのコマンドであるhugoは、サイトをビルドするため、テストすることができます。
  • create-pagesは、静的サイトジェネレーターからページを作成するためのユーザー定義ジョブです。このジョブは、ユーザー定義ジョブ名を使用し、hugoコマンドを実行してサイトをビルドすることができます。次に、pages: trueはこれがPagesジョブであることを指定し、artifactsは生成されたページがpublicというディレクトリに追加されることを指定します。rulesを使用すると、このコミットがデフォルトブランチで行われたことを確認できます。通常、別のブランチからライブサイトをビルドしてデプロイすることは望ましくありません。

このファイルにこれ以上何も追加する必要はありません。準備ができたら、ページ上部の変更をコミットするを選択します。

Hugoサイトをビルドするパイプラインをトリガーすることができました！

GitLab PagesでHugoサイトをデプロイする

すばやく確認すると、GitLabがサイトをビルドし、デプロイしているのを見ることができます。

左側のナビゲーションから、ビルド > パイプラインを選択します。

GitLabがtestとcreate-pagesのジョブを実行したことがわかります。

サイトを表示するには、パイプラインの完了後、左側のナビゲーションでデプロイ > Pagesを選択し、Pagesウェブサイトへのリンクを見つけます。

Hugoの設定オプションを追加する

初めてHugoサイトを表示したとき、スタイルシートが機能しません。心配しないでください。設定ファイルに小さな変更を加える必要があります。HugoがGitLab PagesサイトのURLを知ることで、スタイルシートやその他のアセットへの相対リンクをビルドすることができるようにする必要があります:

  1. ローカルのHugoサイトで最新の変更をプルし、config.yamlまたはconfig.tomlファイルを開きます。
  2. BaseURLパラメータの値を、GitLab Pagesの設定に表示されるURLと一致するように変更します。
  3. 変更したファイルをGitLabにプッシュすると、パイプラインが再度トリガーされるます。

GitLab PagesのURLを見つける

パイプラインが完了したら、デプロイ > Pagesに移動してPagesウェブサイトへのリンクを確認できます。

パイプライン内のpagesジョブが、publicディレクトリのコンテンツをGitLab Pagesにデプロイしました。ページへアクセスの下に、https://<your-namespace>.gitlab.io/<project-path>という形式のリンクが表示されるはずです。

まだパイプラインを実行していない場合は、このリンクは表示されません。

表示されたリンクを選択してサイトを表示します。Hugoの設定でBaseURL設定をGitLabのデプロイURLと一致するように変更する必要があります。

GitLab Pagesの表示レベルを設定する

Hugoサイトがプライベートリポジトリに保存されている場合、Pagesサイトが表示されるように権限を変更する必要があります。そうしないと、プロジェクトメンバーのみに表示されます。サイトの権限を変更するには:

  1. 設定 > 一般 > 可視性、プロジェクトの機能、権限に移動します。
  2. Pagesセクションまでスクロールし、ドロップダウンリストから全員を選択します。
  3. 変更を保存を選択します。

これで誰もがそのURLでサイトを見ることができます。

GitLabでHugoサイトをビルド、テスト、デプロイできました。素晴らしい作業でした！

サイトを変更してGitLabにプッシュするたびに、.gitlab-ci.ymlファイルのルールを使用して、サイトが自動的にビルド、テスト、デプロイされます。

CI/CDパイプラインの詳細については、複雑なパイプラインを作成する方法に関するこのチュートリアルをお試しください。また、利用可能なさまざまな種類のテストについても詳しく学ぶことができます。