Start Building for Free
CircleCI.comアカデミーブログコミュニティサポート

GitLab.com との連携

1 week ago3 min read
クラウド
このページの内容

概要

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

1. ユーザー登録

GitLab との連携は、新規および既存の CircleCI ユーザーに行っていただけます。 CircleCI のユーザー登録 のページに記載されている手順に従ってください。

  • GitLab アカウントを紐付けて組織を作成します。

  • プロジェクトを作成し、GitLab アカウントからリポジトリに接続します。

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

2. 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 に限定されています。 プロジェクトで有効化できるその他の設定については、 設定 のドキュメントを参照してください。

People

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

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

  • Contributor: プロジェクトや一部の設定の読み取りと書き込みアクセス権

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

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

Project roles setup page

設定

この時点で、プロジェクトの設定ソースを追加または削除することができます。 上記の手順で 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 の組織設定に関する一般的な情報は、 設定 を参照してください。

People

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

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

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

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

組織

名前空間の作成

名前空間の管理

組織設定の閲覧

組織設定の管理

組織のアクセス権の閲覧

組織のアクセス権の管理

組織の認証情報の閲覧

組織のポリシーの閲覧

組織のポリシーの管理

組織の連携情報の閲覧

組織の連携情報の管理

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

組織の認証情報の管理

組織の監査ログの閲覧

プランの閲覧

プランの管理

Insights

組織の 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 ベースのトリガーでは、追加のパイプライン値にアクセスできます。 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
      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 でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか

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

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