ドキュメント
circleci.com
Start Building for Free

GitLab.com との連携

1 week ago3 min read
クラウド
On This Page

概要

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

1. 登録

GitLab 連携は、新規および既存の CircleCI ユーザーにご利用いただけます。 新規および既存ユーザーそれぞれに向けた下記手順をお読みください。

2. 新しいプロジェクトを作成する

設定するレポジトリへの API アクセスと書き込みアクセス許可が必要です。 GitLab では、これは "maintainer" 以上のロールです。

アクセストークンを下記手順で使用する場合、 api スコープと write_permissions スコープを選択する必要があります。

  1. CircleCI Web アプリで、Projects に行き、 Create Project ボタンをクリックします。

  2. プロジェクト名を入力します。

  3. Code Source 下に、OAuth 経由、または アクセストークン を使って GitLab に接続するオプションがあります。 いずれかを選択してください。

    OAuth 経由で GitLab に接続する には、Connect ボタンをクリックします。 ブラウザーのウィンドウが開き、GitLab のサインインページに移動します。 GitLab で認証されたら、CircleCI の Create New Project ウィンドウにリダイレクトされます。

    緑色のチェックマークと "CircleCI will listen to your code source for changes." が表示されたら GitLab への接続は成功です。 GitLab リポジトリのドロップダウンリストも表示されます。

    Successful GitLab connection via OAuth

    アクセストークンを使って接続する には、フィールドにアクセストークンを入力し、Connect ボタンをクリックします。 パーソナルアクセストークンまたはプロジェクトアクセストークンを使用できます。 プロジェクトアクセストークンは、特定の GitLab サブスクリプションやライセンス階層でのみ使用できます。 詳細については、GitLab の Personal Access Tokens と Project Access Tokens を参照してください。

    "Access token successful" というメッセージが表示されたら GitLab への接続は成功です。 GitLab リポジトリのドロップダウンリストも表示されます。 セットアップできるリポジトリは、ご使用のパーソナル/プロジェクトアクセストークンに関連づけられてるものによって異なります。

    Successful GitLab connection using access token

  4. 設定するリポジトリを選択し、Create Project をクリックします。

裏では、CircleCI が GitLab リポジトリ内に Webhook を登録しています。 これは、プロジェクトの作成に成功すると、リポジトリの Settings > Webhooks に移動し、確認することができます。

3. CircleCI でプロジェクトパイプラインをトリガーする

現時点では、新しい GitLab プロジェクトを設定しても、パイプラインは自動的にトリガーされません。 また、CircleCI 設定ファイルを CircleCI Web アプリ内で追加または編集することもできません。

  1. まだお済みでない場合は、GitLab リポジトリのルートで .circleci ディレクトリを作成し、そのディレクトリに config.yml ファイルを追加します。

  2. GitLab リポジトリに変更をプッシュします。 CircleCI Web アプリでプロジェクトのパイプラインが実行されているはずです。

    Successful pipeline run

プロジェクト設定

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

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

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

下記の設定は、プロジェクト内で Project Settings ボタンをクリックすると表示されます。 現時点では、設定ファイルもトリガーも GitLab に限定されています。 プロジェクトで有効化できるその他の設定については、 設定　のドキュメントを参照してください。

積極的に開発が進められているプロジェクト設定

設定ファイル

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

Configuration setup page

トリガー

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

Trigger setup page

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

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

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

Trigger details

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

Trigger details

高度な設定

  • 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 の組織設定に関する一般的な情報は、 設定 を参照してください。

チーム

ユーザーを追加または削除し、組織のユーザーロールやユーザーの招待を管理します。

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

新しい組織を作成したら、オプションでダッシュボードからチームメンバーを招待できます。 または、 Organization Settings の People のセクションからチームメンバーを招待することも可能です。

People section under Organization Settings

  1. Invite ボタンをクリックします。

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

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

  3. 招待されたユーザーは、招待を受けるためのリンクが含まれたメール通知 (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 セクションで、複数のアカウント連携を有効化できます。

User account integrations page

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

Connect to GitHub modal

モーダルで Connect をクリックすると、CircleCI アカウントがマージされます。 以前に接続されていた GitLab (つまりスタンドアロン) 組織とは切断されるため、再接続する必要があります。 この切断により、GitLab の組織だけでなく、他のアカウント連携のセキュリティも担保されます。

切断された組織に再び参加するには、 最初のチームメンバーを招待する で説明されているプロセスを通じて再招待される必要があります。

CircleCI で複数のアカウント連携ができることにより、以下が実現できます。

  • アカウントの全てのソースコントロールに容易にアクセスする

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

パイプライン値

GitLab ベースのトリガーでは、追加のパイプライン値にアクセスできます。 CircleCI でのパイプライン値とパラメーターの使用について詳しくは、 パイプライン値とパラメーター を参照して下さい。

名前説明

pipeline.trigger_parameters.circleci.trigger_id

イベントを受信したトリガーの ID

pipeline.trigger_parameters.circleci.config_source_id

設定ソースの ID

pipeline.trigger_parameters.circleci.trigger_type

GitLab

pipeline.trigger_parameters.circleci.event_time

CircleCI のイベント受信のタイムスタンプ

pipeline.trigger_parameters.circleci.event_type

push、pull request、manual など

pipeline.trigger_parameters.circleci.project_id

CircleCI のプロジェクト ID

pipeline.trigger_parameters.circleci.actor_id

CircleCI のユーザー ID

pipeline.trigger_parameters.gitlab.type

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.project_id

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.ref

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.checkout_sha

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.user_id

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.user_name

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.user_username

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.user_avatar

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.repo_name

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.repo_url

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.web_url

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.commit_sha

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.commit_title

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.commit_message

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.commit_timestamp

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.commit_author_name

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.commit_author_email

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.total_commits_count

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.branch

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.default_branch

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.x_gitlab_event_id

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

pipeline.trigger_parameters.gitlab.is_fork_merge_request

GitLab のドキュメントの Webhooks と Webhook events を参照して下さい。

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

GitLab ベースのプロジェクトでは以下のシステム環境変数が使用できません。 パイプラインでこれらの環境変数が必要な場合は、利用可能な パイプライン値 の中の適切な値との置き換えを推奨します。

名前説明

CI_PULL_REQUESTS

現在のビルドに関連付けられたプルリクエストの URL の一覧 (カンマ区切り)。

CI_PULL_REQUEST

関連付けられたプルリクエストの URL。 複数のプル リクエストが関連付けられている場合は、いずれか 1 つの URL がランダムに選択されます。

CIRCLE_PR_NUMBER

関連付けられた GitHub または Bitbucket プルリクエストの番号。 フォークしたプルリクエストのみで使用可能です。

CIRCLE_PR_USERNAME

プルリクエストを作成したユーザーの GitHub または Bitbucket ユーザー名。 フォークしたプルリクエストのみで使用可能です。

CIRCLE_PR_REPONAME

プルリクエストが作成された GitHub または Bitbucket リポジトリの名前。 フォークしたプルリクエストのみで使用可能です。

CIRCLE_PROJECT_USERNAME

現在のプロジェクトの GitHub または Bitbucket ユーザー名。

CIRCLE_PROJECT_REPONAME

現在のプロジェクトのリポジトリの名前。

CIRCLE_REPOSITORY_URL

GitHub または Bitbucket リポジトリ URL。

CIRLCE_SHA1

現在のビルドの前回のコミットの SHA1 ハッシュ。

CIRCLE_TAG

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 でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。

Creative Commons License

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.