GitLab.com との連携
概要
このドキュメントでは、GitLab プロジェクトと CircleCI の連携について説明し、 CI/CD パイプラインを管理するための新しいコンセプトや方法を紹介します。 また、リリース予定の機能の概要もご紹介します。
1. ユーザー登録
GitLab との連携は、新規および既存の CircleCI ユーザーに行っていただけます。 CircleCI のユーザー登録 のページに記載されている手順に従ってください。
-
GitLab アカウントを紐付けて組織を作成します。
-
プロジェクトを作成し、GitLab アカウントからリポジトリに接続します。
リポジトリと CircleCI プロジェクトを接続すると、裏では CircleCI がお客様の GitLab リポジトリ内で Webhook を登録します。 これは、プロジェクトの作成に成功後、リポジトリの Settings > Webhooks のページに移動して確認することができます。
設定するレポジトリへの API アクセスと書き込みアクセス権が必要です。 GitLab では、これは "maintainer" 以上のロールです。 |
2. CircleCI でパイプラインをトリガーする
現時点では、新しい GitLab プロジェクトを設定しても、パイプラインは自動的にトリガーされません。 また、CircleCI 設定ファイルを CircleCI Web アプリ内で追加または編集することもできません。
-
まだお済みでない場合は、GitLab リポジトリのルートで
.circleci
ディレクトリを作成し、そのディレクトリにconfig.yml
ファイルを追加します。CircleCI を初めて利用される方は、最初は Hello World サンプルを使用すること、または サンプル設定ファイル をご覧いただくことをお勧めします。 CircleCI の設定 では、 .circleci/config.yml
で使われるキーをすべて参照できます。 -
GitLab リポジトリに変更をプッシュします。 CircleCI Web アプリでプロジェクトのパイプラインが実行されます。
プロジェクト設定
GitHub プロジェクトや Bitbucket プロジェクトとは異なり、GitLab の連携では、一つの VCS に固有ではない「スタンドアロン」プロジェクトというコンセプトが導入されています。
プロジェクトには 1 つまたは複数の 設定ファイル を含めることができます。設定ファイルとは、リポジトリ内の .circleci/config.yml
ファイルをはじめとする、パイプラインの定義です。
プロジェクトには 1 つまたは複数の トリガー を含めることができます。トリガーとは、VCS をはじめとする、変更ソースからのイベントです。 トリガーによってパイプラインの開始に使用する設定ファイルが決まります。
プロジェクト内で Project Settings ボタンをクリックすると、以下の設定が表示されます。 現時点では、設定ファイルもトリガーも GitLab に限定されています。 プロジェクトで有効化できるその他の設定については、 設定 のドキュメントを参照してください。
People
プロジェクトのロールにより、組織内でどのユーザーがどのプロジェクトにアクセスできるかをさらに細かく制御できます。 チームには自分たちのプロジェクトのみへのアクセス権を付与し、一方管理者などには組織のより広いアクセス権を付与することができます。 アクセス権のオプションは以下の通りです。
-
Admin: プロジェクトや全設定の読み取りと書き込みアクセス権と他のユーザーのアクセス権の管理
-
Contributor: プロジェクトや一部の設定の読み取りと書き込みアクセス権
-
Viewer: プロジェクトや一部の設定の読み取りアクセス権のみ
すべての権限のリストは、 ロールと権限 のセクションをご確認ください。

設定
この時点で、プロジェクトの設定ソースを追加または削除することができます。 上記の手順で GitLab を接続したお客様は、GitLab の設定ソースが自動的に追加されています。 設定ソースを定義すると、その設定ファイルを参照するトリガーをセットアップできます。

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

トリガーとトリガールールにより、CircleCI が変更ソース (この場合はGitLab) からのイベントをどのように処理するかが決まります。
トリガーが作成されると、CircleCI は GitLab に Webhook を登録します。 GitLab からのプッシュイベントは CircleCI に送信されます。 CircleCI はその後、イベントデータを使って、パイプラインを実行すべきかどうかを決定し、実行する場合、どのパイプラインを実行すべきかを決定します。
設定ソースに加えて、各トリガーには Webhook の URL や、このシナリオでは、CircleCI が作成した GitLab トークンも含まれます。 GitLab レポジトリからプッシュイベントを受信するには、GitLab 内で Webhook URLと GitLab トークンを使用して、Webhook をセキュアに登録します。

トリガーのフィルタリング により、Gitlab の Webhook が提供するパラメーターに基づき、トリガーがビルドを開始するタイミングを決定できます。 CircleCI では、一般的なオプションを提供しており、例えば、ビルドはマージリクエストに基づいてのみ行い、フィルタリングのカスタマイズオプションを使って独自のルールを作成することも可能です。 フィルタリングのカスタマイズにより、例えば特定のブランチやユーザーにのみビルドすることができます。

GitLab 連携では、以下のプロジェクト設定の機能の違いにも注意してください。 |
高度な設定
-
CircleCI でセットアップ ワークフローを使って、ダイナミックコンフィグを有効化できます。 ダイナミックコンフィグに関する詳細は、 ダイナミックコンフィグ ガイドをお読みください。
-
現時点では、Free and Open Source 設定はサポートされていませんが、今後提供予定です。
-
現時点では、冗長ワークフローの自動キャンセルはサポートされていません。 詳細については、ジョブやワークフローのスキップやキャンセルに関するドキュメントの 自動キャンセルのセクション を参照してください。
SSH キー
プロジェクトを作成すると、 SSH キーが作成され、リポジトリからコードをチェックアウトする際にに使用されます。 作成した設定ファイルごとに、その設定ファイルに関連づけられたリポジトリのコードにアクセスするための新しい SSH キーが生成されます。 現時点では、GitLab プロジェクトには Additional SSH Keys (追加 SSH キー) のみが適用されます。 SSH キーに関する詳細は、 CircleCI への SSH キーの追加 をご覧ください。
組織設定
GitLab の連携では、特定の VCS に関連づけられない「スタンドアロン」組織のコンセプトも導入されています。
スタンドアロン組織は、VCS に関係なくユーザーやプロジェクトを管理することができます。 組織やユーザーは、CircleCI の組織やユーザーとみなされ、VCS で定義づけられたロールや権限に依存せず、独自のロールや権限を持ちます。
組織レベルで設定を管理するには、CircleCI Web アプリの Organization Settings ボタンをクリックします。 CircleCI の組織設定に関する一般的な情報は、 設定 を参照してください。
People
ユーザーを追加または削除し、組織のユーザーロールやユーザーの招待を管理します。
少なくとも1名の組織管理者が必要です。 最後の組織管理者を削除しようとすると、エラーになります。 |
最初のチームメンバーを招待する
新しい組織を作成したら、オプションでダッシュボードからチームメンバーを招待できます。 または、 Organization Settings の People のセクションからチームメンバーを招待することも可能です。

-
Invite ボタンをクリックします。
-
招待したいユーザーのメールアドレスを入力し、適切なロールを選択します。 複数のユーザーに同じロールをアサインする場合は、複数のアドレスを同時に入力できます。
現時点では、組織管理者ロールと組織コントリビューターロールが使用できます。 プロジェクト固有のロールも間もなく追加されます。 ロールや権限の詳細については、 次のセクション を参照してください。
-
招待されたユーザーは、招待を受けるためのリンクが含まれたメール通知 (
noreply@circleci.com
から送信) を受け取ります。ユーザーが CircleCI アカウントをお持ちでない場合は、登録する必要があります。 既に CircleCI アカウントをお持ちの場合、ユーザーは組織に追加されます。ユーザーがログインすると、Web アプリの左上にある組織切替メニューにその組織がオプションとして表示されます。
ロールと権限
CircleCI のユーザーは、個々の組織で割り当てられたロールによって、可能な操作が異なります。
CircleCI ユーザーのロールと権限は、VCS の権限から派生するものではありません。また、VCS の権限を無視することもできません。 たとえば、CircleCI の Organization Administrator (組織の管理者) である場合、CircleCI 組織内の組織とプロジェクト設定の閲覧および変更が可能です。 しかし、VCS にホストされているプロジェクトの .circleci/config.yml
ファイルを編集するには、VCS のリポジトリ内のプロジェクトに対して書き込みアクセス権が付与されている必要があります。 CircleCI ユーザーの VCS における権限は、関連づけられた GitLab のアイデンティティによって決まります。
現時点では、トリガーや設定ファイルを管理する際に CircleCI と接続することにより GitLab のアイデンティティを管理できます。
組織のロールと権限のマトリックス
アクション | 組織のロール | ||
---|---|---|---|
Admin | Contributor | Viewer | |
組織 | |||
名前空間の作成 | |||
名前空間の管理 | |||
組織設定の閲覧 | |||
組織設定の管理 | |||
組織のアクセス権の閲覧 | |||
組織のアクセス権の管理 | |||
組織の認証情報の閲覧 | |||
組織のポリシーの閲覧 | |||
組織のポリシーの管理 | |||
組織の連携情報の閲覧 | |||
組織の連携情報の管理 | |||
組織のリリース情報の閲覧 | |||
組織の認証情報の管理 | |||
組織の監査ログの閲覧 | |||
プランの閲覧 | |||
プランの管理 | |||
Insights | |||
組織の Insights の閲覧 | |||
ランナー | |||
ランナーの閲覧 | |||
ランナーの管理 | |||
プロジェクト | |||
プロジェクトの閲覧 | |||
プロジェクトの作成 | |||
プロジェクト設定の管理 | |||
プロジェクトのバージョンの復元 | |||
プロジェクトのカナリアの削除 | |||
コンテキスト | |||
コンテキストの閲覧 | |||
コンテキストの使用 | |||
コンテキストの変数の編集 | |||
コンテキストの管理 | |||
Orb | |||
Orb の作成/更新 | |||
プライベート Orb の閲覧 | |||
開発版 Orb のパブリッシュ | |||
Orb のパブリッシュ | |||
Webhook | |||
組織の Webhook の閲覧 | |||
組織の Webhook の管理 | |||
プロジェクトの Webhook の閲覧 | |||
プロジェクトの Webhook の管理 | |||
スケジュール | |||
スケジュールの閲覧 | |||
スケジュールの編集 | |||
トリガー | |||
トリガーの閲覧 | |||
ビルドのトリガー | |||
トリガーの編集 | |||
設定ファイルソース | |||
設定ファイルソースの閲覧 | |||
設定ファイルソースの編集 |
プロジェクトのロールと権限のマトリックス
アクション | プロジェクトのロール | ||
---|---|---|---|
Admin | Contributor | Viewer | |
プロジェクト | |||
プロジェクトの閲覧 | |||
プロジェクトのアクセス権の閲覧 | |||
プロジェクトの認証情報の閲覧 | |||
プロジェクトのバージョンの復元 | |||
プロジェクトのカナリアの削除 | |||
プロジェクトの管理 | |||
Webhook | |||
プロジェクトの Webhook の閲覧 | |||
プロジェクトの Webhook の管理 | |||
スケジュール | |||
スケジュールの閲覧 | |||
スケジュールの編集 | |||
トリガー | |||
トリガーの閲覧 | |||
ビルドのトリガー | |||
トリガーの編集 | |||
設定ファイルソース | |||
設定ファイルソースの閲覧 | |||
設定ファイルソースの編集 |
ユーザー設定
アカウントの連携
CircleCI のユーザープロフィール内の User Settings セクションで、複数のアカウント連携を有効化できます。

CircleCI で複数のアカウント連携ができることにより、以下が実現できます。
-
アカウントの全てのソースコントロールに容易にアクセスする
-
CircleCI で利用可能な全ての認証方法を使用する
パイプライン値
GitLab ベースのトリガーでは、追加のパイプライン値にアクセスできます。 CircleCI でのパイプライン値とパラメーターの使用について詳しくは、 パイプライン値とパラメーター を参照して下さい。
名前 | 説明 |
---|---|
| イベントを受信したトリガーの ID |
| 設定ソースの ID |
| GitLab |
| CircleCI のイベント受信のタイムスタンプ |
| push、pull request、manual など |
| CircleCI のプロジェクト ID |
| CircleCI のユーザー ID |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
| GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。 |
非推奨のシステム環境変数
GitLab ベースのプロジェクトでは以下のシステム環境変数が使用できません。 パイプラインでこれらの環境変数が必要な場合は、利用可能な パイプライン値 の中の適切な値との置き換えを推奨します。
名前 | 説明 |
---|---|
| 現在のビルドに関連付けられたプルリクエストの URL の一覧 (カンマ区切り)。 |
| 関連付けられたプルリクエストの URL。 複数のプル リクエストが関連付けられている場合は、いずれか 1 つの URL がランダムに選択されます。 |
| 関連付けられた GitHub または Bitbucket プルリクエストの番号。 フォークしたプルリクエストのみで使用可能です。 |
| プルリクエストを作成したユーザーの GitHub または Bitbucket ユーザー名。 フォークしたプルリクエストのみで使用可能です。 |
| プルリクエストが作成された GitHub または Bitbucket リポジトリの名前。 フォークしたプルリクエストのみで使用可能です。 |
| 現在のプロジェクトの GitHub または Bitbucket ユーザー名 |
| 現在のプロジェクトのリポジトリの名前 |
| GitHub または Bitbucket リポジトリ URL |
| 現在のビルドの前回のコミットの SHA1 ハッシュ |
| Git タグの名前 (現在のビルドがタグ付けされている場合)。 詳細については、「ワークフローを使用したジョブのオーケストレーション」の Git タグに対応するジョブの実行のセクションを参照してください。 |
パイプラインで上記の環境変数を使用する必要がある場合は、設定ファイルで environment
キー を使用し独自のマッピングを行います。
build:
docker:
- image: cimg/node:17.0
auth:
username: mydockerhub-user
password: $DOCKERHUB_PASSWORD # context / project UI env-var reference
environment:
CIRCLE_PROJECT_REPONAME: << pipeline.trigger_parameters.gitlab.repo_name >>
steps:
- run: echo $CIRCLE_PROJECT_REPONAME
近日公開予定
下記のセクションでは、GitLab 連携では現在はまだフルサポートされていない CircleCI の機能を紹介します。 これらの機能は、今後リリースされる予定です。
アカウントの連携
現在、プロジェクト設定、トリガー、および設定ファイル以外に GitLab との接続を管理する方法はありません。 CircleCI では、ユーザープロフィール内の Account Integration の設定でユーザーの GitLab アイデンティティを管理できるよう取り組んでいます。
冗長ワークフローの自動キャンセル
Auto-cancel redundant workflows (冗長ワークフローの自動キャンセル) は、現在サポートされていません。 この機能は、パイプラインのページからノイズを取り除き、コミットのフィードバックにかかる時間を短縮するためによく使用されます。 詳細は、 ジョブとワークフローのスキップとキャンセル を参照して下さい。
フォークしたプルリクエストにシークレットを渡す
現在、GitLab 連携ではフォークしたプルリクエストにシークレットを渡すオプションはサポートされていません。
ビルドの停止
現在、GitLab 連携では Stop Building オプションをサポートしていません。(このオプションは通常は Project settings 内にあります。) CircleCI パイプラインの実行を停止したい場合は、GitLab リポジトリの Webhook を削除することを推奨します。
SSH での再実行
SSH での再実行は、ユーザーのアカウントが GitLab に加えて Bitbucket または GitHub と連携している場合にのみサポートされます。 ユーザーアカウントの Bitbucket または GitHub の SSH キーは、GitLab の SSH での再実行に使用できます。 ユーザーが SSH キーを管理し、SSH 再実行ができるようにする機能を追加予定です。 SSH での再実行には、コンテキストシークレットは渡されません。 CircleCI では、管理者がシークレットの使用と SSH での再実行をより詳細に制御できるよう取り組んでいます。
追加 SSH キーのみ
GitLab 連携では、デプロイキーとユーザーキーは使用されません。 GitLab のキーは、 Project Settings > Additional SSH Keys に保存されます。 ただし、CircleCI はユーザーがコードのチェックアウトのための SSH キーを手動で管理することを推奨しません。 代わりに、 Set Up Project オプションまたは Project Settings > Configuration を使用し、リポジトリとの接続を維持して下さい。
Free とオープンソースの設定
現在、GitLab のお客様には、オープンソースプランはご利用いただけません。 CircleCI ではオープンソースコミュニティを最新の状態に保ち、将来的にはサポートを提供予定です。
ドキュメントの改善にご協力ください
このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。
- このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
- ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
- CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。 フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。
サポートが必要ですか
CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。
または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.