CircleCI では、バージョン管理システム (VCS) として GitLab をサポートしています。このチュートリアルでは、GitLab でホストしているプロジェクト用の CircleCI CI/CD パイプラインを初めて作成する方法を説明します。GitLab には、SaaS 版とオンプレミスにインストールする self-managed (セルフマネージド) 版がありますが、本記事ではそれぞれと CircleCI との連携方法を解説します。
GitLab CI/CD とは？
GitLab CI/CD とは、GitLab が提供する CI/CD ツールです。GitLab CI/CDでは、第三者が提供しているアプリケーションや連携等を必要とせず、CI/CDを適用することが実現します。CI/CDに関する情報は、こちらのガイドをご覧ください。
前提条件とアプリケーションの基本事項
このチュートリアルを進めるには、以下の準備が必要です。
- Git コマンドの基礎を理解する
- Git をマシンにインストールして利用可能な状態にする
- GitLab アカウントを用意する (SaaS 版と self-managed 版のどちらでも可)
- CircleCI アカウントを用意する
チュートリアル用アプリ
このチュートリアルでは、Web ページに “Hello World” とだけ表示する Python Flask アプリを使用します。アプリでは、必須の依存関係を指定しテストも設定しています。このチュートリアル用アプリは、こちらの GitLab.com で公開しています。
チュートリアル用アプリを、GitLab Web ページの UI からダウンロードするか、Git でクローンしてください。
このチュートリアルの目的上、アプリをゼロから作成する必要はありません。開発手順に興味がある方は、こちらのブログ記事の前半部分をご覧ください。
GitLab の SaaS 版と self-managed 版の違い
先述のとおり、このチュートリアルでは、GitLab の SaaS 版 (GitLab.com) と self-managed 版のそれぞれでホストしているプロジェクトについて、CircleCI パイプラインを設定して実行する方法を紹介します。SaaS 版と self-managed 版の相違点について詳しくは、GitLab のドキュメント (英語) をご覧ください。
SaaS 版 GitLab.com を使用する場合は、まず gitlab.com でユーザー登録を行ってください。その後、GitLab リポジトリにプッシュできるように、GitLab との接続に SSH キーを使用するのであれば SSH キー、HTTPS を使用するのであればパーソナルアクセストークンを作成します。
GitLab self-managed を使用する場合、接続にはインストールしたインスタンスの URL を使用します。この URL は環境によって異なるので、本チュートリアルではプレースホルダーとして yourgitlabinstance.com という URL を使用します。
新規プロジェクトを作成し、チュートリアル用アプリのソースコードを配置します。SaaS 版の場合は gitlab.com/projects/new、self-managed 版の場合は yourgitlabinstance.com/projects/new にアクセスして、プロジェクト新規作成ウィザードを実行してください。
CircleCI コンフィグファイルを作成する
CircleCI を利用するには、まずビルドする対象を指定します。
プロジェクトの一番上に .circleci という新規ディレクトリを作成します。
次に、このディレクトリ内に config.yml というファイルを新しく作成します (.circleci/config.yml)。これが、CircleCI のメインの設定ファイルです。
このファイルに以下のコードを貼り付けます。
version: 2.1
jobs:
test:
docker:
- image: cimg/python:3.10.11
steps:
- checkout
- restore_cache:
key: deps1-{{ .Branch }}-{{ checksum "requirements.txt" }}
- run:
name: Install dependencies
command: |
python3 -m venv venv
. venv/bin/activate
pip install -r requirements.txt
- save_cache:
key: deps1-{{ .Branch }}-{{ checksum "requirements.txt" }}
paths:
- "venv"
- run:
name: Running tests
command: |
. venv/bin/activate
python3 tests.py
- store_artifacts:
path: test-reports/
destination: python_app
workflows:
run-tests:
jobs:
- test
CircleCI コンフィグファイルでは、CircleCI に行わせる処理をすべて定義します。上記のコードでは、1 つのジョブ (test) と、このジョブを含むワークフロー (run-tests) を設定しています。
test ジョブは、Python をインストール済みの Docker コンテナで実行されます。このジョブは、コミットの時点で存在するコードをチェックアウトしてアプリに必要な依存関係 (今回は Flask) をダウンロードし、Python venv を設定してから、tests.py 内のテストを実行します。また、2 回目以降のパイプライン実行を高速化するために依存関係をキャッシュに保存しているほか、CircleCI からアクセスしやすいようにテストアーティファクトの保存も行っています。CircleCI の設定の詳細については、「CircleCI の設定」を参照してください。
保存して新規コミットを作成し、GitLab リポジトリにプッシュします。準備が整ったら、GitLab と CircleCI の連携を設定しましょう。
CircleCI と SaaS 版 GitLab (GitLab.com) を連携する
CircleCI アカウントをお持ちでない場合は、この時点で作成します。https://circleci.com/ja/signup/ にアクセスし、説明に従ってお好みの方法でユーザー登録を行ってください。GitLab を選択すると、GitLab インスタンスを選択するように求められます。[GitLab.com] の隣に表示される [Connect (接続)] をクリックします。
GitLab アカウントに対して CircleCI を認証し、リポジトリへのアクセス権を CircleCI に付与するように求められます。
CircleCI の認証を完了すると、プロジェクト作成ウィザードが表示されます。リストにリポジトリが表示され、先ほどコミットした CircleCI コンフィグファイルが検出されます。
[Create Project (プロジェクトを作成)] をクリックして、ビルドを開始しましょう。これで、CircleCI にプロジェクトが作成されます。後は、変更をコミットおよびプッシュして、初めての CircleCI パイプラインをトリガーするだけです。
README ファイルの更新などの変更を行ってから、コミットしてプッシュしてください。最初のパイプラインが作成され、ビルドが始まり、テストが実行されます。
しばらく待つと、成功を示すメッセージが表示されます。CircleCI パイプラインのステータスは、GitLab の UI にも自動で反映されます。GitLab の左側にある [Build (ビルド)] > [Pipelines (パイプライン)] を選択すると、CircleCI のパイプラインが表示されます。実際の表示例としては、こちらのパブリックプロジェクトをご覧ください。
パイプラインをクリックすると、その詳細が表示されます。[external (外部)] の下に表示される [CircleCI: Workflow run tests] ボタンをクリックすると、CircleCI でワークフローが表示されます。
CircleCI と GitLab self-managed インスタンスを連携する
GitLab self-managed は、SaaS 版とは異なり、ユーザーが管理するインフラ上で実行されます。そのため、インスタンスへのアクセス用の URL もそれぞれ異なります。このチュートリアルでは、インスタンス URL のプレースホルダーとして yourgitlabinstance.com を使用します。また、本セクションの内容は、CircleCI ドキュメントの GitLab との連携方法に関する記事に準拠しています。
GitLab との連携を始める前に、上記の GitLab でのプロジェクト作成と CircleCI コンフィグファイルのコミットを行ってください。
CircleCI アカウントをお持ちでない場合は、この時点で作成します。https://circleci.com/ja/signup/ にアクセスし、説明に従ってお好みの方法でユーザー登録を行ってください。
GitLab を使用して登録すると、GitLab インスタンスを選択するように求められます。[GitLab Self-Managed] の隣に表示される [Connect (接続)] をクリックします。
GitLab self-managed のプロジェクトの設定
ウィザードに従って、プロジェクトの設定を進めます。
まず、GitLab インスタンスの URL を入力して [Verify (確認)] をクリックします。入力した URL の末尾に /api/v4 が追加され、インスタンスの API エンドポイントになります。
API スコープを設定した GitLab のパーソナルアクセストークンを作成し、[Personal Access Token (パーソナルアクセストークン)] フィールドに貼り付けて、[Verify (確認)] をクリックします。
次は、known_hosts 値を入力して [Verify (確認)] をクリックします。値については、ターミナルで ssh-keyscan yourgitlabinstance.com を実行して、出力をまるごと [known_hosts] フィールドに貼り付けてください。これにより、CircleCI で GitLab インスタンスの信頼性確認を行えるようになります。
最後に、ドロップダウンリストでプロジェクトを選択します。cci-python-app など、チュートリアル用に作成したプロジェクトを選択してください。これで、CircleCI でのビルド用に GitLab self-managed プロジェクトが設定されます。
変更をコミットして GitLab リポジトリにプッシュし、パイプラインをトリガーします。これによりワークフローが開始され、しばらくすると CircleCI 上にパイプラインが表示されます。
このパイプラインは、GitLab の左側で [CI/CD] > [Pipelines (パイプライン)] の順に選択して確認することもできます。なお、使用する GitLab のバージョンによっては、下図とは見た目が異なります。
パイプラインのステータスをクリックするとその詳細が表示されます。そこから、CircleCI Web アプリに戻って、プロジェクトおよび CI/CD パイプラインのワークフローとジョブの詳細を確認できます。
お疲れさまでした。これで、GitLab self-managed インスタンス上のプロジェクトを CircleCI でビルドするように設定できました。
まとめ
このチュートリアルでは、初めて CircleCI と GitLab 上のプロジェクトを連携する方向けに、SaaS 版の GitLab (GitLab.com) とオンプレミス版の GitLab セルフマネージド版 の両方の手順を解説しました。
みなさんのご参考となれば幸いです。
