GitLab.com との連携
On This Page
- 概要
- 1. 登録
- 2. 新しいプロジェクトを作成する
- 3. CircleCI でプロジェクトパイプラインをトリガーする
- プロジェクト設定
- 積極的に開発が進められているプロジェクト設定
- 設定ファイル
- トリガー
- 高度な設定
- SSH キー
- 組織設定
- チーム
- 最初のチームメンバーを招待する
- ロールと権限について
- 権限の一覧表
- User settings (ユーザー設定)
- アカウントの連携
- パイプライン値
- 非推奨のシステム環境変数
- 近日公開予定
- アカウントの連携
- プロジェクトのロール
- 冗長ワークフローの自動キャンセル
- コンテキストへのアクセス制限
- フォークしたプルリクエストにシークレットを渡す
- ビルドの停止
- SSH での再実行
- 追加 SSH キーのみ
- Free and open source 設定
- Plan ページの UI
- GitLab のフリープラン
概要
このドキュメントでは、GitLab プロジェクトと CircleCI の連携について説明し、 CI/CD パイプラインを管理するための新しいコンセプトや方法を紹介します。 また、リリース予定の機能の概要もご紹介します。
1. 登録
GitLab 連携は、新規および既存の CircleCI ユーザーにご利用いただけます。 新規および既存ユーザーそれぞれに向けた下記手順をお読みください。
2. 新しいプロジェクトを作成する
設定するレポジトリへの API アクセスと書き込みアクセス許可が必要です。 GitLab では、これは "maintainer" 以上のロールです。
アクセストークンを下記手順で使用する場合、 api
スコープと write_permissions
スコープを選択する必要があります。
-
CircleCI Web アプリで、Projects に行き、 Create Project ボタンをクリックします。
-
プロジェクト名を入力します。
-
Code Source 下に、OAuth 経由、または アクセストークン を使って GitLab に接続するオプションがあります。 いずれかを選択してください。
現時点では、Free プランの GitLab ユーザーはプロジェクトの設定時にパーソナルアクセストークンのみ使用できます。 詳細については、 近日公開予定 のセクションを参照して下さい。 OAuth 経由で GitLab に接続する には、Connect ボタンをクリックします。 ブラウザーのウィンドウが開き、GitLab のサインインページに移動します。 GitLab で認証されたら、CircleCI の Create New Project ウィンドウにリダイレクトされます。
接続するには、OAuth での接続を再試行する必要がある場合があります。 緑色のチェックマークと "CircleCI will listen to your code source for changes." が表示されたら GitLab への接続は成功です。 GitLab リポジトリのドロップダウンリストも表示されます。
アクセストークンを使って接続する には、フィールドにアクセストークンを入力し、Connect ボタンをクリックします。 パーソナルアクセストークンまたはプロジェクトアクセストークンを使用できます。 プロジェクトアクセストークンは、特定の GitLab サブスクリプションやライセンス階層でのみ使用できます。 詳細については、GitLab の Personal Access Tokens と Project Access Tokens を参照してください。
"Access token successful" というメッセージが表示されたら GitLab への接続は成功です。 GitLab リポジトリのドロップダウンリストも表示されます。 セットアップできるリポジトリは、ご使用のパーソナル/プロジェクトアクセストークンに関連づけられてるものによって異なります。
-
設定するリポジトリを選択し、Create Project をクリックします。
裏では、CircleCI が GitLab リポジトリ内に Webhook を登録しています。 これは、プロジェクトの作成に成功すると、リポジトリの Settings > Webhooks に移動し、確認することができます。
3. CircleCI でプロジェクトパイプラインをトリガーする
現時点では、新しい GitLab プロジェクトを設定しても、パイプラインは自動的にトリガーされません。 また、CircleCI 設定ファイルを CircleCI Web アプリ内で追加または編集することもできません。
-
まだお済みでない場合は、GitLab リポジトリのルートで
.circleci
ディレクトリを作成し、そのディレクトリにconfig.yml
ファイルを追加します。CircleCI を初めて利用される方は、<hello-world#echo-hello-world-on-linux#,Hello World>サンプルを使って始めることと、 サンプル設定ファイル をご覧いただくことをお勧めします。 CircleCI の設定 では、 .circleci/config.yml
で使われるキーをすべて参照できます。 -
GitLab リポジトリに変更をプッシュします。 CircleCI Web アプリでプロジェクトのパイプラインが実行されているはずです。
プロジェクト設定
GitHub プロジェクトや Bitbucket プロジェクトとは異なり、GitLab 連携では、一つの VCS に固有ではない「スタンドアロン」プロジェクトというコンセプトが導入されています。
プロジェクトには 1 つまたは複数の 設定ファイル を含めることができます。設定ファイルとは、リポジトリ内の .circleci/config.yml
ファイルをはじめとする、パイプラインの定義です。
プロジェクトには 1 つまたは複数の トリガー を含めることができます。トリガーとは、VCS をはじめとする、変更ソースからのイベントです。 トリガーによってパイプラインの開始に使用する設定ファイルが決まります。
下記の設定は、プロジェクト内で Project Settings ボタンをクリックすると表示されます。 現時点では、設定ファイルもトリガーも GitLab に限定されています。 プロジェクトで有効化できるその他の設定については、 設定 のドキュメントを参照してください。
積極的に開発が進められているプロジェクト設定
設定ファイル
現在、プロジェクトの設定ソースを追加または削除することができます。 上記の手順で 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 の組織設定に関する一般的な情報は、 設定 を参照してください。
チーム
ユーザーを追加または削除し、組織のユーザーロールやユーザーの招待を管理します。
少なくとも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 | |
組織 | |||
組織設定の管理 | |||
組織設定の閲覧 | |||
プランの管理 | |||
プランの閲覧 | |||
インサイト | |||
組織のインサイトの閲覧 | |||
ランナー | |||
ランナーの管理 | |||
ランナーの閲覧 | |||
プロジェクト | |||
プロジェクト設定の管理 | |||
プロジェクトの閲覧 | |||
コンテキスト | |||
コンテキストの管理 | |||
コンテキストの閲覧 | |||
コンテキストの使用 | |||
Orb | |||
名前空間の管理 | |||
Orb カテゴリーの更新 | |||
Orb の作成/更新 | |||
Orb のパブリッシュ | |||
開発版 Orb のパブリッシュ | |||
プライベート Orb の閲覧 |
User settings (ユーザー設定)
アカウントの連携
CircleCI のユーザープロフィール内の User Settings セクションで、複数のアカウント連携を有効化できます。

既にGitLab アカウントに接続している状態で、GitHub やBitbucket とのアカウント連携を追加するために Connect をクリックすると、以下のようなモーダルが表示されます。

モーダルで Connect をクリックすると、CircleCI アカウントがマージされます。 以前に接続されていた GitLab (つまりスタンドアロン) 組織とは切断されるため、再接続する必要があります。 この切断により、GitLab の組織だけでなく、他のアカウント連携のセキュリティも担保されます。
切断された組織に再び参加するには、 最初のチームメンバーを招待する で説明されているプロセスを通じて再招待される必要があります。
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
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 (冗長ワークフローの自動キャンセル) は、現在サポートされていません。 この機能は、パイプラインのページからノイズを取り除き、コミットのフィードバックにかかる時間を短縮するためによく使用されます。 詳細は、 ジョブとワークフローのスキップとキャンセル を参照して下さい。
コンテキストへのアクセス制限
コンテキストへのアクセス制限は現在サポートされていません。 ソースからパイプラインをトリガーできるユーザーなら誰でも、コンテキストを使用できます。 将来的には、コンテキストを制限する複数の方法を提供予定です。
CircleCI でのコンテキストの使用に関する詳細は、 コンテキストの使用 を参照してください。
フォークしたプルリクエストにシークレットを渡す
現在、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 and open source 設定
現在、GitLab のお客様には、オープンソースプランはご利用いただけません。 CircleCI ではオープンソースコミュニティへの対応を続け、将来的にはサポートを提供予定です。
Plan ページの UI
現在、Plan ページの Plan セクションを表示すると、左上に組織名ではなく組織の UUID が表示されます。
GitLab のフリープラン
GitLab アカウントが対応している場合、CircleCI はプロジェクト設定時に可能な限り GitLab プロジェクトトークンを作成します。 GitLab のフリープランを使用している場合、プロジェクトトークンを作成できないため、CircleCI はパーソナル API トークンを要求し、使用します。 有料プランを利用中で、プロジェクトのセットアップ時にパーソナル API トークンを入力した場合は、CircleCI は入力された パーソナル API トークンを使用してプロジェクトトークンを作成しますのでご注意下さい。
ドキュメントの改善にご協力ください
このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。
- このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
- ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
- CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。 フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。
サポートが必要ですか
CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。
または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.