無料でビルドを開始
CircleCI.comアカデミーブログコミュニティサポート

GitLab との連携

8 months ago3 min read
クラウド
このページの内容

概要

このドキュメントでは、GitLab プロジェクトと CircleCI の連携方法について説明し、 CI/CD パイプラインを管理するための新しいコンセプトや方法を紹介します。 また、リリース予定の機能の概要もご紹介します。

ユーザー登録

GitLab との連携は、新規および既存の CircleCI ユーザーに行っていただけます。 「 CircleCI のユーザー登録」に記載されている手順に従い、GitLab アカウントを連携し組織を作成してください。

リポジトリと CircleCI プロジェクトを連携すると、CircleCI により GitLab リポジトリ内に Webhook が登録されます。 これは、プロジェクトの作成に成功後、リポジトリの [Settings (設定)] > Webhooks のページに移動して確認することができます。

現在、GitLab との連携には下記の制限があります。

  • 各ユーザーが作成できる組織は最大 3 つです。

  • Free プランでは、各組織が作成できるプロジェクトは最大 10 個です。

組織やプロジェクトを追加する必要がある場合は、 有料プランへのアップグレードをご検討いただくか、または サポートチームにお問い合わせください。

CircleCI でパイプラインをトリガーする

GitLab リポジトリに変更をプッシュするたびに、新しいパイプラインがトリガーされ、CircleCI Web アプリ内の該当するプロジェクトでそのパイプラインが実行中になります。

Successful pipeline run

現在、Web アプリ内で既存の CircleCI 設定ファイルを編集することはできません。 設定ファイルに変更を加える場合は、GitLab リポジトリで行ってください。

セットアップ後、リポジトリに変更をコミットすると、パイプラインが自動的にトリガーされます。 ただし、現時点では、CircleCI Web アプリからパイプラインを手動でトリガーすることはできません。

プロジェクト設定

GitHub プロジェクトや Bitbucket プロジェクトとは異なり、GitLab の連携では、一つの VCS に固有ではない「スタンドアロン」プロジェクトというコンセプトが導入されています。

プロジェクトには 1 つ以上の設定ファイルを含めることができます。設定ファイルとは、リポジトリ内の .circleci/config.yml ファイルをはじめとする、パイプラインの定義です。

プロジェクトには 1 つ以上のトリガーを含めることができます。トリガーとは、VCS をはじめとする、変更ソースからのイベントです。 トリガーによってパイプラインの開始に使用する設定ファイルが決まります。

プロジェクト内で [Project Settings (プロジェクト設定)] ボタンをクリックすると、以下の設定が表示されます。 現時点では、設定ファイルもトリガーも GitLab に限定されています。

People (メンバー)

プロジェクトのロールにより、組織内でどのユーザーがどのプロジェクトにアクセスできるかを細かく制御できます。 これにより、チームには自分たちのプロジェクトのみへのアクセス権を付与し、一方で管理者には組織のより広いアクセス権を付与する、といった制御が可能になります。 アクセス権のオプションは以下の通りです。

  • Admin (管理者): プロジェクトや全設定の読み取りと書き込みアクセス権、および他のユーザーのアクセス権の管理

  • Contributor (コントリビューター): プロジェクトや一部の設定の読み取りと書き込みアクセス権

  • Viewer (閲覧者): プロジェクトや一部の設定の読み取りアクセス権のみ

すべての権限のリストは、「 ロールと権限」セクションをご確認ください。

Project roles setup page

Configuration (設定ファイル)

現時点では、プロジェクトの設定ソースを追加または削除することができます。 上記の手順で GitLab と連携した場合は、GitLab の設定ソースが自動的に追加されています。

GitLab self-managed を使用している場合は、追加済みのインスタンスを設定ソースとして選択できます。 self-managed インスタンスの別の feature ブランチやリポジトリを新しい設定ソースとして使用する場合は、まず [Organization Settings (組織設定)] で新規連携を追加する必要があります。 どちらの場合でも、再びパーソナルアクセストークンを入力して連携を認証するように求められます。

設定ソースを定義すると、その設定ファイルを参照するトリガーをセットアップできます。

Configuration setup page

Triggers (トリガー)

現時点では、パイプラインのスケジュール実行機能を GitLab で使用することはできません。GitLab のトリガーについては以下をお読みください。フィルタリング機能を使い、特定の条件に基づいてパイプラインをトリガーする方法も紹介しています。

パイプラインを開始する設定ソースを指定するトリガーを追加します。 上記の手順で GitLab と連携した場合は、GitLab が設定ソースとして設定されたトリガーが自動的に追加されています。

Trigger setup page

トリガーとトリガールールにより、CircleCI で変更ソース (この場合はGitLab) からのイベントをどのように処理するかが決まります。

トリガーが作成されると、CircleCI により Webhook が GitLab に登録されます。 GitLab からのプッシュイベントは CircleCI に送信されます。 CircleCI はその後、イベントデータを使って、パイプラインを実行すべきかどうかを決定し、実行する場合、どのパイプラインを実行すべきかを決定します。

各トリガーには、設定ソースに加えて、Webhook の URL のほか、このシナリオでは CircleCI で作成された GitLab トークンも含まれます。 GitLab レポジトリからプッシュイベントを受信するために、Webhook URL と GitLab トークンを使用して、GitLab に Webhook がセキュアに登録されます。

Trigger details

トリガーのフィルタリングにより、GitLab の Webhook に用意されているパラメーターに基づき、トリガーがビルドを開始するタイミングを決定できます。 CircleCI では、一般的なオプション (マージリクエスト時のみビルドを行うなど) を使用できるほか、フィルタリングのカスタマイズオプションを使って独自のルールを作成することも可能です。 たとえば、ビルドの開始条件を特定のブランチやユーザーに設定できます。

Trigger details

Advanced (高度な設定)

  • CircleCI のセットアップワークフローを使って、ダイナミックコンフィグを有効化できます。 ダイナミックコンフィグに関する詳細は、「 ダイナミックコンフィグ」を参照してください。

  • 現時点では、[Free and Open Source (Free プランのオープンソース)] 設定はサポートされていませんが、今後提供予定です。

  • 現時点では、冗長ワークフローの自動キャンセルはサポートされていません。 詳細については、ジョブとワークフローの`スキップ`や`キャンセル`について説明した 自動キャンセルに関するセクションを参照してください。

プロジェクトの SSH キー

プロジェクトを作成すると、リポジトリからコードをチェックアウトするための SSH キーが作成されます。 作成した設定ファイルごとに、その設定ファイルに関連づけられたリポジトリのコードにアクセスするための SSH キーが新しく生成されます。 現時点では、[Additional SSH Keys (追加の SSH キー)] 設定は、GitLab プロジェクトにのみ適用されます。

GitLab SSH キーを作成する

  1. GitLab の説明に従って、SSH キーペアを作成します。 パスワードを入力するよう求められた場合、入力しないでください (以下に、macOS でキーを生成するコマンドの一例を示します)。

      ssh-keygen -t ed25519 -C "your_email@example.com"
  2. GitLab のプロジェクトにアクセスし、[Settings (設定)] > [Repository (リポジトリ)] に移動し、[Deploy keys (デプロイキー)] セクションを展開します。 [Title (タイトル)] フィールドにタイトルを入力し、手順 1 で作成したパブリックキーをコピー&ペーストします。 [Grant write permissions to this key (このキーに書き込み権限を付与)] にチェックを入れ、[Add Key (キーを追加)] をクリックします。

  3. CircleCI アプリのプロジェクトの設定にアクセスし、[SSH Keys (SSH キー)] > [Add SSH key (SSH キーを追加)] の順に選択します。 [Hostname (ホスト名)] フィールドに gitlab.com と入力し、手順 1 で作成したプライベートキーを追加します。 次に [Add SSH Key (SSH キーを追加)] をクリックします。

  4. .circleci/config.yml ファイルで、add_ssh_keys キーを使用してジョブにフィンガープリントを追加します。

      version: 2.1
    
      jobs:
        deploy-job:
          steps:
            - add_ssh_keys:
                fingerprints:
                  - "SO:ME:FIN:G:ER:PR:IN:T"

ジョブから GitLab リポジトリにプッシュすると、CircleCI は追加された SSH キーを使用します。

SSH キーに関する詳細は、「 CircleCI に SSH キーを登録する」をご覧ください。

組織設定

GitLab の連携では、特定の VCS に関連づけられない「スタンドアロン」組織のコンセプトも導入されています。

スタンドアロン組織は、VCS に関係なくユーザーやプロジェクトを管理することができます。 組織やユーザーは、CircleCI の組織やユーザーとみなされ、VCS で定義づけられたロールや権限に依存せず、独自のロールや権限を持ちます。

組織レベルで設定を管理するには、CircleCI Web アプリの [Organization Settings (組織設定)] ボタンをクリックします。

People (メンバー)

ユーザーの追加と削除、および組織のユーザーロールとユーザー招待の管理を行えます。

最初のチームメンバーを招待する

新しい組織を作成したら、任意でダッシュボードからチームメンバーを招待できます。 また、[Organization Settings (組織設定)][People (メンバー)] セクションからチームメンバーを招待することも可能です。

People section under Organization Settings
  1. [Invite (招待)] ボタンをクリックします。

  2. 招待したいユーザーのメールアドレスを入力し、適切なロールを選択します。 複数のユーザーに同じロールをアサインする場合は、複数のアドレスを同時に入力できます。

    現時点では、組織管理者ロールと組織コントリビューターロールが使用できます。 プロジェクト固有のロールも間もなく追加されます。 詳細については、「 ロールと権限」セクションを参照してください。

  3. 招待したユーザーには、招待を受けるためのリンクが記載されたメール通知 (noreply@circleci.com から送信) が届きます。

    招待したユーザーが CircleCI アカウントをお持ちでない場合は、ユーザー登録を行う必要があります。 既に CircleCI アカウントをお持ちの場合、ユーザーは組織に追加されます。ユーザーがログインすると、Web アプリの左上にある組織切替メニューにその組織がオプションとして表示されます。

[Integrations (連携)] (GitLab self-managed のみ)

GitLab self-managed の組織の場合、別の self-managed インスタンスを追加して組織に連携することができます。

  1. [Organization Settings (組織設定)][Integrations (連携)] に移動して、新しいインスタンスを追加します。

    Add a new self-managed instance on the Integrations page
  2. ユーザー登録」セクションの説明に従い、インスタンス URL を入力します。

GitLab.com を使用している場合は、 ユーザー設定でアカウント連携を管理できます。

SSH ホストの信頼性の確立

GitLab self-managed インスタンスの場合、CircleCI が接続先のホストの信頼性を検証できるように、"既知のホスト" ファイル (~/.ssh/known_hosts) に SSH ホストキーを追加する必要があります。 インスタンスのパブリックホストキーは、CircleCI ジョブでコードをチェックアウトする際にリモートホストの身元を確認できるように、[known_hosts (既知のホスト)] フィールドに保存されます。

リモートサーバーの SSH キーは、ssh-keyscan <host> コマンド (例: ssh-keyscan test-gitlab.circleci.com) を実行すると取得できます。

ホストキーの取得時には、フィンガーブリントを調べることでキーが適切かどうかを検証できます。 フィンガーブリントは、self-managed インスタンスの [Help (ヘルプ)] ページの [Instance Configuration (インスタンス設定)] セクションで確認できます ( インスタンス設定に関するこちらのページ (英語) を参照)。

ロールと権限

CircleCI のユーザーは、個々の組織で割り当てられたロールによって、可能な操作が異なります。

CircleCI ユーザーのロールと権限は、VCS の権限から派生するものではありません。また、VCS の権限を無視することもできません。 たとえば、CircleCI の Organization Administrator (組織管理者) である場合、CircleCI 組織内の組織とプロジェクト設定の閲覧および変更が可能です。 しかし、VCS にホストされているプロジェクトの .circleci/config.yml ファイルを編集するには、VCS のリポジトリ内のプロジェクトに対して書き込みアクセス権が付与されている必要があります。 CircleCI ユーザーの VCS における権限は、関連づけられた GitLab のアイデンティティによって決まります。

現時点では、トリガーや設定ファイルを管理する際に CircleCI と連携することにより GitLab のアイデンティティを管理できます。

組織のロールと権限のマトリックス

アクション組織のロールAdmin (管理者)

Contributor (コントリビューター)

Viewer (閲覧者)

組織

名前空間の作成

名前空間の管理

組織設定の閲覧

組織設定の管理

組織のアクセス権の閲覧

組織のアクセス権の管理

組織の認証情報の閲覧

組織のポリシーの閲覧

組織のポリシーの管理

組織の連携情報の閲覧

組織の連携情報の管理

組織のリリース情報の閲覧

組織の認証情報の管理

組織の監査ログの閲覧

プランの閲覧

プランの管理

インサイト

組織の Insights の閲覧

ランナー

ランナーの閲覧

ランナーの管理

プロジェクト

プロジェクトの閲覧

プロジェクトの作成

プロジェクト設定の管理

プロジェクトのバージョンの復元

プロジェクトのカナリアの削除

コンテキスト

コンテキストの閲覧

コンテキストの使用

コンテキストの変数の編集

コンテキストの管理

Orb

Orb の作成/更新

プライベート Orb の閲覧

開発版 Orb のパブリッシュ

Orb のパブリッシュ

Webhook

組織の Webhook の閲覧

組織の Webhook の管理

プロジェクトの Webhook の閲覧

プロジェクトの Webhook の管理

スケジュール

スケジュールの閲覧

スケジュールの編集

トリガー

トリガーの閲覧

ビルドのトリガー

トリガーの編集

設定ファイルソース

設定ファイルソースの閲覧

設定ファイルソースの編集

プロジェクトのロールと権限のマトリックス

アクションプロジェクトのロールAdmin (管理者)

Contributor (コントリビューター)

Viewer (閲覧者)

プロジェクト

プロジェクトの閲覧

プロジェクトのアクセス権の閲覧

プロジェクトの認証情報の閲覧

プロジェクトのバージョンの復元

プロジェクトのカナリアの削除

プロジェクトの管理

Webhook

プロジェクトの Webhook の閲覧

プロジェクトの Webhook の管理

スケジュール

スケジュールの閲覧

スケジュールの編集

トリガー

トリガーの閲覧

ビルドのトリガー

トリガーの編集

設定ファイルソース

設定ファイルソースの閲覧

設定ファイルソースの編集

ユーザー設定

アカウントの連携

CircleCI のユーザープロフィール内の [User Settings (ユーザー設定)] セクションで、複数のアカウント連携を有効化できます。

User account integrations page

CircleCI で複数のアカウントと連携すると、以下のメリットがあります。

  • アカウントの全てのソースコントロールにアクセスしやすくなる

  • CircleCI で利用可能な全ての認証方法を使用できる

非推奨のシステム環境変数

GitLab ベースのプロジェクトでは、一部の定義済み環境変数を使用できません。 「プロジェクトの値と変数」の 定義済み環境変数の表で、環境変数ごとの VCS 対応状況を参照してください。 パイプラインでこれらの環境変数が必要な場合は、 パイプライン値の表に記載されている適切な値との置き換えを推奨します。

近日公開予定の機能

下記のセクションでは、現段階の GitLab 連携ではまだフルサポートされていない CircleCI の機能を紹介します。 これらの機能は、今後リリースされる予定です。

アカウントの連携

現在、プロジェクト設定、トリガー、および設定ファイル以外に GitLab との連携を管理する方法はありません。 CircleCI では、ユーザープロフィール内の [Account Integrations (アカウント連携)] でユーザーの GitLab アイデンティティを管理できるよう取り組んでいます。

冗長ワークフローの自動キャンセル

冗長ワークフローの自動キャンセルは、現時点ではサポートされていません。 この機能の主な用途は、パイプラインのページからノイズを取り除き、コミットのフィードバックにかかる時間を短縮することです。 詳細は、 ジョブとワークフローのスキップとキャンセルを参照して下さい。

フォークしたプルリクエストにシークレットを渡す

現在、GitLab 連携では、フォークしたプルリクエストにシークレットを渡すオプションはサポートされていません。

ビルドの停止

現在、GitLab 連携では、[Stop Building (ビルドの停止)] オプションをサポートしていません。他の連携では、このオプションは [Project settings (プロジェクト設定)] に表示されます。 CircleCI パイプラインの実行を停止したい場合は、GitLab リポジトリの Webhook を削除することを推奨します。

SSH での再実行

SSH での再実行は、アカウントを GitLab に加えて Bitbucket または GitHub と連携している場合にのみサポートされます。 ユーザーアカウントの Bitbucket または GitHub の SSH キーを使用して、GitLab について SSH での再実行を行えます。 CircleCI では、SSH での再実行を可能にするため、SSH の管理機能を追加予定です。 SSH での再実行では、コンテキストシークレットは渡されません。 CircleCI では、管理者がシークレットの使用と SSH での再実行をより詳細に制御できるよう取り組んでいます。

追加の SSH キーのみ

GitLab の連携では、デプロイキーとユーザーキーは使用されません。 GitLab のキーは、[Project Settings (プロジェクト設定)] > [Additional SSH Keys (追加の SSH キー)] に保存されます。 ただし、コードのチェックアウト用の SSH キーを手動で管理することは推奨されません。 代わりに、[Set Up Project (プロジェクトをセットアップ)] オプションまたは [Project Settings (プロジェクト設定)] > [Configuration (設定ファイル)] を使用し、リポジトリとの連携を維持して下さい。

[Free and open source (Free プランのオープンソース)] 設定

現在、GitLab のお客様は、オープンソースプランをご利用いただけません。 CircleCI では、このプランの対象 VCS の拡大を進めており、最新情報についてはオープンソースコミュニティにお知らせします。

テストインサイト

テスト インサイト機能は現在、GitLab のお客様には対応しておりません。


Suggest an edit to this page

Make a contribution
Learn how to contribute