GitとCI/CDに関する知識ゼロのSEが、GitLab.comのCI/CDパイプラインをAPIで外部から実行してみるだけ

皆様こんにちは。SEの小池と申します。

GitLabには超強力なCI/CDパイプライン機能が備わっています。
実はこのCI/CDパイプライン、プロジェクトの公開範囲にかかわらず結構簡単にAPIで外部から実行することができます。

今回のブログでは、GitLab.com に作成した CI/CDパイプラインを API で外部からトリガーしてみます。

本記事の対象の方
今回のブログのゴール
このブログをお読みいただくにあたっての事前ご連絡事項
最初に結論
Step1 : テスト用のプロジェクトを準備する
Step2 : トリガートークンを作る
Step3 : 外部からAPIでCI/CDパイプラインをお試し実行
最後に

本記事の対象の方

GitLabに作成したCI/CDパイプラインを外部からAPIでトリガーしたい方。

今回のブログのゴール

このブログのゴールはこちらです。

今回のゴール

GitLab.comに作成したCI/CDパイプラインを外部からAPIでトリガーする。

このブログをお読みいただくにあたっての事前ご連絡事項

本記事はSaaS版 (GitLab.com) の Enterprise Edition 15.10.0-pre における仕様をベースに記載しております。それ以外のエディションやバージョンではこの記事に記載の通りではない可能性がございます。
本記事の操作説明と画面ショットはGitLabのローカライズを日本語にした状態で説明しております。それ以外の言語をご利用の方は適宜読み替えてください。
本記事はGitやCI/CDに関する知識ゼロのSEによるなんちゃって記事です。GitLabのディープな使用法についてはGitLabの公式オンラインドキュメント (こちら) をご参照ください。

最初に結論

GitLabではSaaS版かSelf-Managed版かを問わず、外部からAPIで対象プロジェクトのCI/CDパイプラインを実行することができます。

方法は、対象プロジェクトの設定で トリガートークン を作成し、APIの引数でそれを指定するだけです。

2023/03/06現時点で、本機能はFree版でも利用可能です。

参考：Trigger pipelines by using the API | GitLab

Step1 : テスト用のプロジェクトを準備する

最初に、テスト用のプロジェクトと、テスト用のCI/CDパイプラインを準備をします。
既存のプロジェクト及び CI/CDパイプラインを用いる場合は、このステップをスキップして Step2 から実施してください。

まず、適当にテスト用のプロジェクトを作成します。
この際、公開範囲は問いません。パブリックでも、プライベートでも構いません。
このブログではプライベートにしています。

作成したテスト用プロジェクトに、CI/CDパイプラインを作成します。
このパイプラインは中身は何でも構いません。
このブログでは以下のように、ステージsample-stage01があり、ジョブsample-job01でechoとdateを実行するだけの超ドシンプルなCI/CDパイプラインにしました。

stages:
  - sample-stage01

sample-job0:
  stage: sample-stage01
  script:
    - echo "外部からAPIでトリガーできるかのお試し用CI/CDパイプラインです。"
    - date

最後に、このCI/CDパイプラインが現時点で正常に実行できることを確認してください。

以上でテスト用プロジェクトとテスト用CI/CDパイプラインの準備は完了です。

Step2 : トリガートークンを作る

Step1で準備したプロジェクトでトリガートークンを作成します。

対象プロジェクトの [設定] > [CI/CD] を開き、[パイプラインのトリガー] を展開します。

[Description] に適当な説明を記載し、[トリガーを追加] をクリックします。

トークンが生成されることを確認します。
トークンは次のStepで使用するので、コピーボタンでコピーしておきます。

以上でトリガートークンの作成は完了です。

Step3 : 外部からAPIでCI/CDパイプラインをお試し実行

では、実際に外部からAPIで対象プロジェクトのCI/CDパイプラインを実行してみます。

コマンドは、Step2の [パイプラインのトリガー] セクションの下にあるものをコピーするか・・・

あるいはこちらのGitLab Docsをご参照いただき、該当するコマンドをコピーしてください。

このブログではシンプルに以下のコマンドをベースにします。
(以下のサンプルのプロジェクトIDは架空の文字列です。ご自身のプロジェクトIDに読み替えてください。)

curl -X POST \
     --fail \
     -F token=TOKEN \
     -F ref=REF_NAME \
     https://gitlab.com/api/v4/projects/12345678/trigger/pipeline

引数tokenに、Step2で作成したトリガートークンを指定します。
また、引数refにはブランチ名かタグを指定します。ここでは例としてブランチ "main" を指定します

curl -X POST \
     --fail \
     -F token=<Step2で作成したトリガートークン> \
     -F ref=main \
     https://gitlab.com/api/v4/projects/12345678/trigger/pipeline

コマンドを実行します。
(下図はWindowsのコマンドプロンプトから実行している例です。)

GitLabの対象プロジェクトの画面から、CI/CDパイプラインが実行されたことを確認してみます。
対象プロジェクトのページを開き、[CI/CD] > [パイプライン] をクリックします。

新しく実行履歴ができていました！！！

ジョブ名をクリックして、スクリプト内部の実行履歴も確認してみます。
正常にechoとdateが実行されていました。

この様に、対象プロジェクトにトリガートークンを設定することで、GitLabのCI/CDパイプラインを外部からAPIで実行することができます。

最後に

この度はGitもCI/CDもよくわかっていないど素人SEによるGitLab検証ブログをお読みいただき、誠にありがとうございます。
このブログの目標は以下のとおりでしたが、皆さまはいかがでしたでしょうか。

今回のゴール

GitLab.comに作成したCI/CDパイプラインを外部からAPIでトリガーする。

CI/CDパイプラインは、リポジトリでコミットが発生したら、自動でビルドしてテストして・・・という処理を自動化するのが一般的な用途です。

しかし、そもそもリポジトリのコミットをCI/CDパイプラインのトリガーにしたくない、リポジトリとはあまり関係ない処理をCI/CDで組んでいる、なんてケースもあるかと存じます。
こういった場合は、今回ご紹介いたしましたトリガートークンを用いた外部からのCI/CDパイプライン実行が使えるかもしれません。
もしよろしければご検討・ご試行いただければと存じます。

この記事がGitLabを触り始めた方の一助となれば幸いにございます。

GitLabに関するお問い合わせは、以下のフォームからお願い致します。
GitLab製品お問い合わせ

今までのGitLabの検証ブログはこちらです。