チュートリアル: GitLab Pagesウェブサイトをゼロから作成する

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このチュートリアルでは、Jekyll静的サイトジェネレーター（SSG）を使用して、Pagesサイトをゼロから作成する方法を説明します。空のプロジェクトから開始し、Runnerに指示を与えるCI/CD設定ファイルを自分で作成します。CI/CDパイプラインを実行すると、Pagesサイトが作成されます。

この例ではJekyllを使用していますが、他のSSGでも同様の手順を実行します。このチュートリアルを完了するために、JekyllまたはSSGに精通している必要はありません。

GitLab Pagesウェブサイトを作成するには:

前提要件

GitLabに空のプロジェクトが必要です。

プロジェクトファイルを作成する

ルート（トップレベル）ディレクトリに次の3つのファイルを作成します:

.gitlab-ci.yml: 実行するコマンドを含むYAMLファイル。今のところ、ファイルの内容は空白のままにしておきます。
index.html: 次のような、必要なHTMLコンテンツを入力できる空でないHTMLファイル。たとえば、次のようなファイルです:
```
<html>
<head>
  <title>Home</title>
</head>
<body>
  <h1>Hello World!</h1>
</body>
</html>
```
Gemfile: Rubyプログラムの依存関係を記述するファイル。
次の内容を入力します:
```
source "https://rubygems.org"

gem "jekyll"
```

Dockerイメージを選択する

この例では、RunnerはDockerイメージを使用してスクリプトを実行し、サイトをデプロイします。

この特定のRubyイメージは、DockerHubで保持されます。

.gitlab-ci.ymlファイルの先頭に次のCI/CD設定を追加して、デフォルトのイメージをパイプラインに追加します:

default:
  image: ruby:3.2

ビルドするためにSSGにNodeJSが必要な場合は、ファイルシステムの一部としてNodeJSを含むイメージを指定する必要があります。たとえば、Hexoサイトの場合は、image: node:12.17.0を使用できます。

Jekyllをインストールする

Jekyllをローカルで実行するには、インストールする必要があります:

ターミナルを開きます。
gem install bundlerを実行して、Bundlerをインストールします。
bundle installを実行して、Gemfile.lockを作成します。
bundle exec jekyll buildを実行して、Jekyllをインストールします。

プロジェクトでJekyllを実行するには、.gitlab-ci.ymlファイルを編集して、インストールコマンドを追加します:

script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build

さらに、.gitlab-ci.ymlファイルでは、各scriptはjobで整理されます。jobには、特定のタスクに適用するスクリプトと設定が含まれています。

job:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build

GitLab Pagesの場合、このjobには、pagesというプロパティを含める必要があります。この設定は、ジョブでGitLab Pagesを使用してウェブサイトをデプロイすることをRunnerに伝えます:

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build
  pages: true  # specifies that this is a Pages job

このページの例では、ユーザー定義のジョブ名を使用します。

出力用の`public`ディレクトリを指定する

Jekyllは、どこに出力を生成するのかを知る必要があります。GitLab Pagesは、publicというディレクトリ内のファイルのみを考慮します。

Jekyllは、宛先フラグ（-d）を使用して、ビルドされたウェブサイトの出力ディレクトリを指定します。.gitlab-ci.ymlファイルに宛先を追加します:

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job

アーティファクト用の`public`ディレクトリを指定する

Jekyllがファイルをpublicディレクトリに出力したので、Runnerはどこからファイルを取得するのかを知る必要があります。GitLab 17.10以降では、Pagesジョブの場合のみ、pages.publishパスが明示的に指定されていない場合、publicディレクトリが自動的にartifacts:pathsに付け加えられます:

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory

.gitlab-ci.ymlファイルは次のようになるはずです:

default:
  image: ruby:3.2

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory

ウェブサイトをデプロイして表示する

上記の手順を完了したら、ウェブサイトをデプロイします:

.gitlab-ci.ymlファイルを保存してコミットします。
ビルド > パイプラインに移動して、パイプラインを監視します。
パイプラインが完了したら、デプロイ > Pagesに移動して、Pages Webサイトへのリンクを見つけます。

このpagesジョブが正常に完了すると、特別なpages:deployジョブがパイプラインビューに表示されます。このジョブは、GitLab Pagesデーモン用のウェブサイトのコンテンツを準備します。GitLabはこのジョブをバックグラウンドで実行し、Runnerを使用しません。

CI/CDファイルのその他のオプション

より高度なタスクを実行する場合は、.gitlab-ci.ymlファイルを他のCI/CD YAMLキーワードで更新できます。GitLabに用意されているCI Lintツールを使用して、.gitlab-ci.ymlファイルを検証できます。

次のトピックでは、CI/CDファイルに追加できるその他のオプションの例を示します。

特定のブランチをPagesサイトにデプロイする

特定のブランチからのみPagesサイトにデプロイすることをお勧めします。

まず、workflowセクションを追加して、変更がブランチにプッシュされた場合にのみパイプラインが実行されるようにします:

default:
  image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory

次に、デフォルトブランチ（ここではmain）に対してのみジョブを実行するようにパイプラインを設定します。

default:
  image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

create-pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

デプロイするステージを指定する

GitLab CI/CDには、Build、Test、Deployの3つのデフォルトステージがあります。

スクリプトをテストし、本番環境にデプロイする前にビルドされたサイトを確認する場合は、デフォルトブランチ（ここではmain）にプッシュするときのテストとまったく同じようにテストを実行できます。

ジョブを実行するステージを指定するには、stage行をCIファイルに追加します:

default:
  image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

create-pages:
  stage: deploy
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment: production

次に、CIファイルに別のジョブを追加して、mainブランチをexcept（除く）すべてのブランチへのすべてのプッシュをテストするように指示します:

default:
  image: ruby:3.2

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

create-pages:
  stage: deploy
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment: production

test:
  stage: test
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d test
  artifacts:
    paths:
      - test
  rules:
    - if: $CI_COMMIT_BRANCH != "main"

testステージでtestジョブが実行されると、Jekyllはtestというディレクトリにサイトをビルドします。ジョブは、mainを除くすべてのブランチに影響します。

ステージを複数のジョブに適用すると、同じステージに含まれるすべてのジョブが並列でビルドします。Webアプリケーションをデプロイする前に複数のテストが必要な場合は、すべてのテストを同時に実行できます。

重複するコマンドを削除する

すべてのジョブで同じbefore_scriptコマンドを複製しないようにするために、そのコマンドをデフォルトセクションに追加できます。

この例では、gem install bundlerとbundle installは、pagesとtestの両方のジョブで実行されていました。

これらのコマンドをdefaultセクションに移動します:

default:
  image: ruby:3.2
  before_script:
    - gem install bundler
    - bundle install

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

create-pages:
  stage: deploy
  script:
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment: production

test:
  stage: test
  script:
    - bundle exec jekyll build -d test
  artifacts:
    paths:
      - test
  rules:
    - if: $CI_COMMIT_BRANCH != "main"

キャッシュされた依存関係を使用してより高速にビルドする

より高速にビルドするには、cacheパラメータを使用して、プロジェクトの依存関係のインストールファイルをキャッシュできます。

この例では、bundle installを実行すると、Jekyllの依存関係がvendorディレクトリにキャッシュされます:

default:
  image: ruby:3.2
  before_script:
    - gem install bundler
    - bundle install --path vendor
  cache:
    paths:
      - vendor/

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH


create-pages:
  stage: deploy
  script:
    - bundle exec jekyll build -d public
  pages: true  # specifies that this is a Pages job and publishes the default public directory
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment: production

test:
  stage: test
  script:
    - bundle exec jekyll build -d test
  artifacts:
    paths:
      - test
  rules:
    - if: $CI_COMMIT_BRANCH != "main"

この場合、Jekyllがビルドするフォルダーのリストから/vendorディレクトリを除外する必要があります。そうしないと、Jekyllはディレクトリの内容をサイトとともにビルドしようとします。

ルートディレクトリに、_config.ymlというファイルを作成し、次の内容を追加します:

exclude:
  - vendor

これで、GitLab CI/CDはウェブサイトをビルドするだけでなく、次のことも行います:

continuous tests（継続的テスト）でフィーチャーブランチにプッシュします。
Bundlerでインストールされた依存関係をCaches（キャッシュ）します。
mainブランチへのすべてのプッシュをContinuously deploys（継続的にデプロイ）します。

サイト用に作成されたHTMLおよびその他の資産を表示するには、ジョブアーティファクトをダウンロードします。