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

このチュートリアルでは、JekyllStatic Site Generator(SSG)を使ってゼロから Pages サイトを作成する方法を紹介します。空白のプロジェクトから始め、独自の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 ファイルを編集し、最初の行に次のテキストを追加してください：

image: ruby:2.7

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

Jekyllのインストール

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

  1. あなたのターミナルを開きます。
  2. gem install bundler を実行してBundlerをインストールします。
  3. bundle install を実行してGemfile.lock を作成します。
  4. bundle exec jekyll build を実行して Jekyll をインストールします。

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

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

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

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

GitLab Pagesの場合、このjob はpages という特定の名前を持っています。この設定は、ジョブに GitLab Pages を使ってウェブサイトをデプロイさせたいことを Runner に伝えます：

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

出力用のpublic ディレクトリを指定します。

Jekyllは、その出力を生成する場所を知る必要があります。GitLab Pagesはpublic と呼ばれるディレクトリ内のファイルのみを考慮します。

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

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public

アーティファクトのpublic ディレクトリを指定します。

今、Jekyllはpublic ディレクトリにファイルを出力している、ランナーはそれらを取得する場所を知る必要があります。アーティファクトは、public ディレクトリに格納されています：

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public

あなたの.gitlab-ci.yml ファイルは現在、次のようになります：

image: ruby:2.7

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public

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

前述の手順を完了したら、ウェブサイトをデプロイします：

  1. .gitlab-ci.yml ファイルを保存してコミットします。
  2. Build > Pipelinesでパイプラインを確認します。
  3. パイプラインが完了したら、[デプロイ] > [Pages]でPagesウェブサイトへのリンクを探します。

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

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

より高度な作業を行いたい場合は、.gitlab-ci.yml 利用可能な設定を使ってファイルを .gitlab-ci.yml更新することができます。GitLabに含まれているCI Lintツールでファイルを.gitlab-ci.yml 検証することが .gitlab-ci.ymlできます。

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

Pages サイトへの特定のブランチのデプロイ

特定のブランチからのみPagesサイトにデプロイしたい場合があります。

まず、workflow セクションを追加して、変更がブランチにプッシュされたときだけパイプラインを実行するようにします：

image: ruby:2.7

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

pages:
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public

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

image: ruby:2.7

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

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

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

GitLab CI/CDのデフォルトステージは、ビルド、テスト、デプロイの3つです。

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

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

image: ruby:2.7

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

pages:
  stage: deploy
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  environment: production

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

image: ruby:2.7

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

pages:
  stage: deploy
  script:
    - gem install bundler
    - bundle install
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  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 を除くすべてのブランチに影響を与えます。

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

重複コマンドの削除

ジョブごとに同じスクリプトが重複しないように、before_script セクションに追加することができます。

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

これらのコマンドをbefore_script セクションに移動してください：

image: ruby:2.7

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

before_script:
  - gem install bundler
  - bundle install

pages:
  stage: deploy
  script:
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  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 を実行すると、vendor ディレクトリにJekyllの依存関係をキャッシュします：

image: ruby:2.7

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

cache:
  paths:
    - vendor/

before_script:
  - gem install bundler
  - bundle install --path vendor

pages:
  stage: deploy
  script:
    - bundle exec jekyll build -d public
  artifacts:
    paths:
      - public
  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はウェブサイトをビルドするだけでなく、次のようなこともできるようになりました：

  • 機能ブランチに継続的にテストをプッシュします。
  • Bundlerでインストールされた依存関係をキャッシュします。
  • main ブランチへのすべてのプッシュを継続的にデプロイします。

サイト用に作成された HTML やその他のアセットを見るには、ジョブのアーティファクトをダウンロードしてください。