前書き

GitLab Community Editionは、プロジェクト管理とソフトウェア開発を支援する追加機能を備えた自己ホスト型のGitリポジトリプロバイダーです。 GitLabが提供する最も価値のある機能の1つは、https://about.gitlab.com/features/gitlab-ci-cd/ [GitLab CI]と呼ばれる組み込みの継続的統合および配信ツールです。

このガイドでは、GitLab CIをセットアップしてリポジトリの変更を監視し、自動テストを実行して新しいコードを検証する方法を示します。 基本的なNode.jsアプリケーションのサンプルリポジトリをコピーする、実行中のGitLabインストールから始めます。 CIプロセスを設定した後、新しいコミットがリポジトリにプッシュされると、GitLabはCIランナーを使用して、隔離されたDockerコンテナ内のコードに対してテストスイートを実行します。

前提条件

始める前に、初期環境をセットアップする必要があります。 コードを保存し、CI / CDプロセスを管理するように構成された安全なGitLabサーバーが必要です。 さらに、自動テストを実行する場所が必要です。 これは、GitLabがインストールされているサーバーまたは別のホストのいずれかです。 以下のセクションでは、要件について詳しく説明します。

SSLで保護されたGitLabサーバー

ソースコードを保存してCI / CDタスクを構成するには、Ubuntu 16.04サーバーにインストールされたGitLabインスタンスが必要です。 GitLabは現在、少なくとも* 2 CPUコア*および* 4GBのRAM *を搭載したサーバーを推奨しています。 コードの公開や改ざんから保護するために、GitLabインスタンスはLet’s Encryptを使用してSSLで保護されます。 この手順を完了するには、サーバーにドメイン名またはサブドメインが関連付けられている必要があります。

次のチュートリアルを使用して、これらの要件を完了できます。

プロジェクト間でCI / CDランナー(自動テストを実行するコンポーネント)を共有する方法と、それらを単一のプロジェクトにロックする方法を示します。 プロジェクト間でCIランナーを共有する場合は、パブリックサインアップを制限または無効にすることを強くお勧めします。 インストール中に設定を変更しなかった場合は、戻ってhttps://www.digitalocean.com/community/tutorials/how-to-install-and-configure-gitlab-on-ubuntu-16-04#restrictに従ってください-または-disable-public-sign-ups-(オプション)[サインアップの制限または無効化に関するGitLabインストール記事のオプションのステップ]を使用して、外部の第三者による悪用を防止します。

GitLab CIランナーとして使用する1つ以上のサーバー

GitLab CI Runnerは、コードをチェックアウトし、自動テストを実行して新しい変更を検証するサーバーです。 テスト環境を分離するために、Dockerコンテナー内ですべての自動テストを実行します。 これを行うには、テストを実行するサーバーにDockerをインストールする必要があります。

この手順は、GitLabサーバーまたは別のUbuntu 16.04サーバーで実行して、分離を強化し、リソースの競合を回避できます。 次のチュートリアルでは、テストの実行に使用するホストにDockerをインストールします。

開始する準備ができたら、このガイドに進みます。

GitHubからサンプルリポジトリをコピーする

まず、サンプルのNode.jsアプリケーションを含む新しいプロジェクトをGitLabで作成します。 GitHubから元のリポジトリを直接インポートするを使用すると、手動でアップロードする必要がなくなります。

GitLabにログインして、右上隅の*プラスアイコン*をクリックし、[新しいプロジェクト]を選択して新しいプロジェクトを追加します。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/new_project_icon_3.png [GitLab新しいプロジェクトの追加アイコン]

新しいプロジェクトページで、[プロジェクトのインポート]タブをクリックします。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/import-project.png [GitLab新しいプロジェクト名]

次に、[* Repo by URL *]ボタンをクリックします。 GitHubインポートオプションがありますが、個人アクセストークンが必要であり、リポジトリと追加情報をインポートするために使用されます。 コードとGit履歴にのみ関心があるため、URLによるインポートは簡単です。

  • GitリポジトリURL *フィールドに、次のGitHubリポジトリURLを入力します。

https://github.com/do-community/hello_hapi.git

これは次のようになります。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/new_project_github_url2.png [GitLab新規プロジェクトGitHub URL]

これはデモンストレーションであるため、リポジトリを* Private *とマークしておくのがおそらく最善です。 完了したら、[プロジェクトの作成]をクリックします。

新しいプロジェクトは、GitHubからインポートされたリポジトリに基づいて作成されます。

.gitlab-ci.ymlファイルについて

GitLab CIは、各リポジトリ内で「+ .gitlab-ci.yml 」というファイルを探して、コードのテスト方法を決定します。 インポートしたリポジトリには、プロジェクト用に設定済みの ` gitlab-ci.yml +`ファイルがあります。 この形式の詳細については、https://docs.gitlab.com/ce/ci/yaml/README.html [.gitlab-ci.ymlリファレンスドキュメント]をご覧ください。

作成したプロジェクトのGitLabインターフェースで、「+。gitlab-ci.yml +」ファイルをクリックします。 CI構成は次のようになります。

gitlab-ci.yml
image: node:latest

stages:
 - build
 - test

cache:
 paths:
   - node_modules/

install_dependencies:
 stage: build
 script:
   - npm install
 artifacts:
   paths:
     - node_modules/

test_with_lab:
 stage: test
 script: npm test

このファイルはhttps://docs.gitlab.com/ee/ci/yaml/[GitLab CI YAML構成構文]を使用して、実行するアクション、実行する順序、実行する条件、各タスクを完了するために必要なリソース。 独自のGitLab CIファイルを作成する場合、GitLabインスタンスの `+ / ci / lint +`に移動して、ファイルが正しくフォーマットされていることを検証することにより、構文リンターにアクセスできます。

設定ファイルは、テストスイートの実行に使用するDocker `+ image +`を宣言することから始まります。 HapiはNode.jsフレームワークであるため、最新のNode.jsイメージを使用しています。

image: node:latest

次に、実行するさまざまな連続統合ステージを明示的に定義します。

stages:
 - build
 - test

ここで選択する名前は任意ですが、順序によって、後続のステップの実行順序が決まります。 ステージは、個々のジョブに適用できるタグです。 GitLabは同じステージのジョブを並行して実行し、現在のステージのすべてのジョブが完了するまで次のステージの実行を待機します。 ステージが定義されていない場合、GitLabは「+ build」、「+ test」、「+ deploy」という3つのステージを使用し、デフォルトですべてのジョブを「+ test +」ステージに割り当てます。

ステージを定義した後、設定には `+ cache +`定義が含まれます:

cache:
 paths:
   - node_modules/

これは、実行またはステージ間でキャッシュ(後で使用するために保存)できるファイルまたはディレクトリを指定します。 これにより、実行間で変化しない可能性のあるリソースに依存するジョブの実行にかかる時間を短縮できます。 ここでは、 `+ node_modules `ディレクトリをキャッシュしています。ここで、 ` npm +`がダウンロードした依存関係をインストールします。

最初の仕事は `+ install_dependencies +`と呼ばれます:

install_dependencies:
 stage: build
 script:
   - npm install
 artifacts:
   paths:
     - node_modules/

ジョブには任意の名前を付けることができますが、名前はGitLab UIで使用されるため、わかりやすい名前が役立ちます。 通常、 `+ npm install +`は次のテストステージと組み合わせることができますが、ステージ間の相互作用をよりよく示すために、このステップを抽出して独自のステージで実行します。

`+ stage `ディレクティブでステージを明示的に“ build”としてマークします。 次に、 ` script `ディレクティブを使用して実行する実際のコマンドを指定します。 ` script +`セクション内に行を追加して、複数のコマンドを含めることができます。

`+ artifacts `サブセクションは、保存またはステージ間で渡すファイルまたはディレクトリのパスを指定するために使用されます。 ` npm install `コマンドはプロジェクトの依存関係をインストールするため、次のステップではダウンロードしたファイルにアクセスする必要があります。 ` node_modules `パスを宣言すると、次のステージでファイルにアクセスできるようになります。 これらは、テスト後にGitLab UIで表示またはダウンロードすることもできるため、バイナリなどのビルドアーティファクトにも役立ちます。 ステージ中に作成されたすべてを保存したい場合は、 ` paths `セクション全体を ` untracked:true +`に置き換えます。

最後に、 `+ test_with_lab +`という2番目のジョブは、テストスイートを実際に実行するコマンドを宣言します。

test_with_lab:
 stage: test
 script: npm test

これを「+ test 」ステージに配置します。 これは後の段階なので、 ` build `ステージによって生成されたアーティファクトにアクセスできます。これは、この場合のプロジェクトの依存関係です。 ここで、 ` script +`セクションは、アイテムが1つしかない場合に使用できる1行のYAML構文を示しています。 コマンドが1つしか指定されていないため、前のジョブでも同じ構文を使用できました。

`+ .gitlab-ci.yml +`ファイルがCI / CDタスクをどのように定義するかについての基本的な考え方ができたので、テスト計画を実行できる1人以上のランナーを定義できます。

継続的インテグレーションの実行のトリガー

リポジトリには `+ .gitlab-ci.yml +`ファイルが含まれているため、新しいコミットは新しいCIの実行をトリガーします。 ランナーがいない場合、CIの実行は「保留」に設定されます。 ランナーを定義する前に、CI実行をトリガーして、保留状態のジョブがどのように見えるかを確認しましょう。 ランナーが利用可能になると、すぐに保留中のランが選択されます。

+ hello_hapi + GitLabプロジェクトリポジトリビューに戻り、ブランチとプロジェクト名の横の*プラス記号*をクリックして、メニューから*新しいファイル*を選択します。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/new_file_button2.png [GitLab新規ファイルボタン]

次のページで、「ファイル名」フィールドに「+ dummy_file +」と入力し、メインの編集ウィンドウにテキストを入力します。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/dummy_file2.png [GitLabダミーファイル]

終了したら、下部の[* Commit changes *]をクリックします。

ここで、プロジェクトのメインページに戻ります。 小さな*一時停止*アイコンが最新のコミットに添付されます。 アイコンの上にマウスを置くと、「Commit:pending」と表示されます。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/pending_marker_2.png [GitLab保留マーカー]

これは、コードの変更を検証するテストがまだ実行されていないことを意味します。

詳細については、ページの上部に移動して[パイプライン]をクリックしてください。 パイプラインの概要ページが表示され、CI実行が保留中としてマークされ、「スタック」としてラベル付けされていることがわかります。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_index_stuck.png [GitLabパイプラインインデックスのスタック]

ここから、* pending *ステータスをクリックして、実行の詳細を取得できます。 このビューには、実行のさまざまな段階と、各段階に関連付けられた個々のジョブが表示されます。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_detail_view.png [GitLabパイプライン詳細ビュー]

最後に、* install_dependencies *ジョブをクリックします。 これにより、実行が遅延しているものに関する特定の詳細が表示されます。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/job_detail_view.png [GitLabジョブ詳細ビュー]

このメッセージは、ランナーが不足しているためにジョブが停止していることを示しています。 まだ設定していないため、これは予想されています。 ランナーが利用可能になると、この同じインターフェイスを使用して出力を確認できます。 これは、ビルド中に生成されたアーティファクトをダウンロードできる場所でもあります。

保留中のジョブがどのように見えるかがわかったので、CIランナーをプロジェクトに割り当てて保留中のジョブを取得できます。

GitLab CI Runner Serviceのインストール

これで、GitLab CIランナーをセットアップする準備が整いました。 これを行うには、システムにGitLab CIランナーパッケージをインストールし、GitLabランナーサービスを開始する必要があります。 サービスは、異なるプロジェクトに対して複数のランナーインスタンスを実行できます。

前提条件で述べたように、リソースの競合を確実に回避したい場合は、GitLabインスタンスをホストする同じサーバーまたは別のサーバーでこれらの手順を実行できます。 どのホストを選択したとしても、使用する構成にはDockerがインストールされている必要があります。

GitLab CIランナーサービスのインストールプロセスは、GitLab自体のインストールに使用されるプロセスに似ています。 GitLabリポジトリを `+ apt +`ソースリストに追加するスクリプトをダウンロードします。 スクリプトを実行した後、ランナーパッケージをダウンロードします。 その後、GitLabインスタンスを提供するように構成できます。

GitLab CIランナーリポジトリ構成スクリプトの最新バージョンを `+ / tmp +`ディレクトリにダウンロードすることから始めます(これはGitLabサーバーで使用されるリポジトリとは異なるリポジトリです)。

curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh -o /tmp/gl-runner.deb.sh

ダウンロードしたスクリプトを自由に調べて、実行するアクションに慣れていることを確認してください。 スクリプトhttps://packages.gitlab.com/runner/gitlab-ci-multi-runner/install[here]のホストバージョンを見つけることもできます。

less /tmp/gl-runner.deb.sh

スクリプトの安全性に満足したら、インストーラーを実行します。

sudo bash /tmp/gl-runner.deb.sh

このスクリプトは、GitLabが管理するリポジトリを使用するようにサーバーをセットアップします。 これにより、他のシステムパッケージに使用するのと同じパッケージ管理ツールを使用してGitLabランナーパッケージを管理できます。 これが完了すると、 `+ apt-get`を使用してインストールを続行できます。

sudo apt-get install gitlab-runner

これにより、GitLab CIランナーパッケージがシステムにインストールされ、GitLabランナーサービスが開始されます。

GitLabランナーのセットアップ

次に、作業の受け入れを開始できるようにGitLab CIランナーを設定する必要があります。

これを行うには、ランナーがGitLabサーバーで認証できるように、GitLabランナートークンが必要です。 必要なトークンのタイプは、このランナーの使用方法によって異なります。

*プロジェクト固有のランナー*は、ランナーに特定の要件がある場合に役立ちます。 たとえば、 `+ gitlab-ci.yml +`ファイルが資格情報を必要とするデプロイメントタスクを定義している場合、特定のランナーがデプロイメント環境で正しく認証される必要がある場合があります。 プロジェクトにCIプロセスでリソースを大量に消費するステップがある場合、これも良いアイデアです。 プロジェクト固有のランナーは、他のプロジェクトからのジョブを受け入れません。

一方、*共有ランナー*は、複数のプロジェクトで使用できる汎用ランナーです。 ランナーは、各プロジェクトで現在実行されているジョブの数を考慮したアルゴリズムに従って、プロジェクトからジョブを取得します。 このタイプのランナーはより柔軟です。 共有ランナーをセットアップするには、管理者アカウントでGitLabにログインする必要があります。

これらの両方のランナータイプのランナートークンを取得する方法を以下に示します。 最適な方法を選択してください。

プロジェクト固有のランナーを登録するための情報の収集

ランナーを特定のプロジェクトに関連付けたい場合は、GitLabインターフェースでプロジェクトのページに移動することから始めます。

ここから、左側のメニューの[設定]項目をクリックします。 その後、サブメニューの* CI / CD *アイテムをクリックします。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/project_settings_item2.png [GitLabプロジェクト設定項目]

このページには、*ランナーの設定*セクションが表示されます。 * Expand *ボタンをクリックして詳細を表示します。 詳細ビューでは、左側にプロジェクト固有のランナーを登録する方法が説明されています。 手順のステップ4で表示された登録トークンをコピーします。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/specific_runner_config_settings2.png [GitLab固有のランナー構成設定]

このプロジェクトでアクティブな共有ランナーを無効にする場合は、右側の[共有ランナーを無効にする]ボタンをクリックして無効にします。 これはオプションです。

準備ができたら、このページから収集した情報を使用してランナーを登録する方法を学びましょう。

情報を収集して共有ランナーを登録する

共有ランナーを登録するために必要な情報を見つけるには、管理者アカウントでログインする必要があります。

最初に、上部のナビゲーションバーにある*レンチアイコン*をクリックして、管理領域にアクセスします。 左側のメニューの[概要]セクションで、[ランナー]をクリックして、共有ランナー構成ページにアクセスします。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/admin_area_icon2.png [GitLab管理エリアアイコン]

ページの上部に表示される登録トークンをコピーします。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/shared_runner_token2.png [GitLab共有ランナートークン]

このトークンを使用して、プロジェクトのGitLab CIランナーを登録します。

GitLab CIランナーをGitLabサーバーに登録する

トークンを取得したら、GitLab CIランナーサービスがインストールされているサーバーに戻ります。

新しいランナーを登録するには、次のコマンドを入力します。

sudo gitlab-runner register

ランナーを構成するための一連の質問が表示されます。

`+ https:// `を使用してSSLを指定し、GitLabサーバーのドメイン名を入力します。 オプションで、ドメインの末尾に「 / ci +」を追加できますが、最近のバージョンでは自動的にリダイレクトされます。

このランナーのgitlab-ciトークンを入力してください

最後のセクションでコピーしたトークン。

このランナーのgitlab-ciの説明を入力してください

この特定のランナーの名前。 これは、コマンドラインおよびGitLabインターフェースのランナーサービスのランナーリストに表示されます。

このランナーのgitlab-ciタグを入力してください(カンマ区切り)

これらは、ランナーに割り当てることができるタグです。 GitLabジョブは、これらのタグに関する要件を表現して、正しい依存関係を持つホストで実行されることを確認できます。

この場合、空白のままにしておくことができます。

*ランナーを現在のプロジェクトにロックするかどうか[true / false] *

ランナーを特定のプロジェクトに割り当てます。 他のプロジェクトでは使用できません。

ここで「false」を選択します。

エグゼキューターを入力してください

ランナーがジョブを完了するために使用する方法。

ここで「docker」を選択します。

デフォルトのDockerイメージを入力してください(例: ルビー:2.1)

`+ .gitlab-ci.yml `ファイルに画像仕様が含まれていない場合にジョブを実行するために使用されるデフォルトの画像。 ここで一般的な画像を指定し、 ` .gitlab-ci.yml +`ファイルでより具体的な画像を定義することをお勧めします。

ここでは、小さく安全なデフォルトとして「alpine:latest」と入力します。

プロンプトに答えると、プロジェクトのCI / CDタスクを実行できる新しいランナーが作成されます。

次のように入力すると、GitLab CIランナーサービスで現在利用可能なランナーを確認できます。

sudo gitlab-runner list
OutputListing configured runners                          ConfigFile=/etc/gitlab-runner/config.toml
example-runner                                      Executor=docker Token=e746250e282d197baa83c67eda2c0b URL=https://example.com

ランナーが利用可能になったので、GitLabのプロジェクトに戻ることができます。

GitLabでのCI / CD実行の表示

Webブラウザーに戻り、GitLabのプロジェクトに戻ります。 ランナーを登録してからの時間に応じて、ランナーは現在実行中の場合があります。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/ci_running_icon_2.png [GitLab CI実行アイコン]

または、すでに完了している可能性があります。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/ci_run_passed_icon_2.png [GitLab CI実行合格アイコン]

状態に関係なく、実行中*または*合格*アイコン(または問題が発生した場合は*失敗)をクリックして、CI実行の現在の状態を表示します。 上部の[パイプライン]メニューをクリックして、同様のビューを取得できます。

GitLab CI実行のステータスを確認できるパイプラインの概要ページに移動します。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_run_overview.png [GitLab CIパイプライン実行の概要]

  • Stages *ヘッダーの下に、実行中の各ステージのステータスを示す円があります。 ステージをクリックすると、ステージに関連付けられている個々のジョブを確認できます。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_run_stage_view.png [GitLab CIパイプライン実行stage_view]

  • build ステージ内の install_dependencies *ジョブをクリックします。 これにより、ジョブの概要ページが表示されます。

image:https://assets.digitalocean.com/articles/gitlab_ci_usage/pipeline_job_overview.png [GitLab CIパイプラインジョブの概要]

現在、使用可能なランナーがないというメッセージを表示する代わりに、ジョブの出力が表示されます。 私たちの場合、これは各パッケージをインストールする `+ npm +`の結果を見ることができることを意味します。

右側に沿って、他のアイテムも表示されます。 * Stage *を変更して、以下の実行をクリックすると、他のジョブを表示できます。 実行によって生成されたアーティファクトを表示またはダウンロードすることもできます。

結論

このガイドでは、GitLab CIの継続的な統合および展開機能を紹介するデモプロジェクトをGitLabインスタンスに追加しました。 `+ gitlab-ci.yml +`ファイルでパイプラインを定義してアプリケーションをビルドおよびテストする方法と、ジョブをステージに割り当てて相互の関係を定義する方法について説明しました。 次に、GitLab CIランナーを設定して、プロジェクトのCIジョブを取得し、個々のGitLab CI実行に関する情報を見つける方法を示しました。