正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

パイプラインスケジュールAPI

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このAPIを使用して、パイプラインスケジュールを操作します。

すべてのパイプラインスケジュールを取得

プロジェクトのパイプラインスケジュールのリストを取得します。

GET /projects/:id/pipeline_schedules
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
scope文字列いいえパイプラインスケジュールのスコープ。次のいずれかである必要があります。active、inactive。
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"
[
    {
        "id": 13,
        "description": "Test schedule pipeline",
        "ref": "refs/heads/main",
        "cron": "* * * * *",
        "cron_timezone": "Asia/Tokyo",
        "next_run_at": "2017-05-19T13:41:00.000Z",
        "active": true,
        "created_at": "2017-05-19T13:31:08.849Z",
        "updated_at": "2017-05-19T13:40:17.727Z",
        "owner": {
            "name": "Administrator",
            "username": "root",
            "id": 1,
            "state": "active",
            "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
            "web_url": "https://gitlab.example.com/root"
        }
    }
]

単一のパイプラインスケジュールを取得

プロジェクトのパイプラインスケジュールを取得します。

GET /projects/:id/pipeline_schedules/:pipeline_schedule_id
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
pipeline_schedule_id整数はいパイプラインスケジュールのID。
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
{
    "id": 13,
    "description": "Test schedule pipeline",
    "ref": "refs/heads/main",
    "cron": "* * * * *",
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T13:41:00.000Z",
    "active": true,
    "created_at": "2017-05-19T13:31:08.849Z",
    "updated_at": "2017-05-19T13:40:17.727Z",
    "last_pipeline": {
        "id": 332,
        "sha": "0e788619d0b5ec17388dffb973ecd505946156db",
        "ref": "refs/heads/main",
        "status": "pending"
    },
    "owner": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
        "web_url": "https://gitlab.example.com/root"
    },
    "variables": [
        {
            "key": "TEST_VARIABLE_1",
            "variable_type": "env_var",
            "value": "TEST_1",
            "raw": false
        }
    ],
    "inputs": [
        {
            "name": "deploy_strategy",
            "value": "blue-green"
        },
        {
            "name": "feature_flags",
            "value": ["flag1", "flag2"]
        }
    ]
}

パイプラインスケジュールによってトリガーされたすべてのパイプラインを取得

プロジェクト内のパイプラインスケジュールによってトリガーされたすべてのパイプラインを取得します。

GET /projects/:id/pipeline_schedules/:pipeline_schedule_id/pipelines

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
pipeline_schedule_id整数はいパイプラインスケジュールのID。

リクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/pipelines"

レスポンス例:

[
  {
    "id": 47,
    "iid": 12,
    "project_id": 29,
    "status": "pending",
    "source": "scheduled",
    "ref": "new-pipeline",
    "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
    "web_url": "https://example.com/foo/bar/pipelines/47",
    "created_at": "2016-08-11T11:28:34.085Z",
    "updated_at": "2016-08-11T11:32:35.169Z"
  },
  {
    "id": 48,
    "iid": 13,
    "project_id": 29,
    "status": "pending",
    "source": "scheduled",
    "ref": "new-pipeline",
    "sha": "eb94b618fb5865b26e80fdd8ae531b7a63ad851a",
    "web_url": "https://example.com/foo/bar/pipelines/48",
    "created_at": "2016-08-12T10:06:04.561Z",
    "updated_at": "2016-08-12T10:09:56.223Z"
  }
]

新しいパイプラインスケジュールを作成

プロジェクトの新しいパイプラインスケジュールを作成します。

POST /projects/:id/pipeline_schedules
属性型必須説明
cron文字列はいCronスケジュール（例：0 1 * * *）。
description文字列はいパイプラインスケジュールの説明。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
ref文字列はいパイプラインをトリガーするブランチまたはタグ名。短いrefs（例：main）と完全なrefs（例：refs/heads/mainまたはrefs/tags/main）の両方を受け入れます。短いrefsは自動的に完全なrefsに展開されますが、refがあいまいな場合、リクエストは拒否されます。
activeブール値いいえパイプラインスケジュールをアクティブにします。falseが設定されている場合、パイプラインスケジュールは最初に非アクティブ化されます（デフォルト：true）。
cron_timezone文字列いいえActiveSupport::TimeZoneでサポートされているタイムゾーン（例：Pacific Time (US & Canada)）（デフォルト：UTC）。
inputsハッシュいいえパイプラインスケジュールに渡すinputsの配列。各入力には、nameとvalueが含まれています。値には、文字列、配列、数値、またはブール値を指定できます。

リクエスト例:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules" \
  --form "description=Build packages" \
  --form "ref=main" \
  --form "cron=0 1 * * 5" \
  --form "cron_timezone=UTC" \
  --form "active=true"

レスポンス例:

{
    "id": 14,
    "description": "Build packages",
    "ref": "refs/heads/main",
    "cron": "0 1 * * 5",
    "cron_timezone": "UTC",
    "next_run_at": "2017-05-26T01:00:00.000Z",
    "active": true,
    "created_at": "2017-05-19T13:43:08.169Z",
    "updated_at": "2017-05-19T13:43:08.169Z",
    "last_pipeline": null,
    "owner": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
        "web_url": "https://gitlab.example.com/root"
    }
}

inputsを使用したリクエストの例:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules" \
  --form "description=Build packages" \
  --form "ref=main" \
  --form "cron=0 1 * * 5" \
  --form "cron_timezone=UTC" \
  --form "active=true" \
  --form "inputs[][name]=deploy_strategy" \
  --form "inputs[][value]=blue-green"

パイプラインスケジュールを編集する

プロジェクトのパイプラインスケジュールを更新します。更新が完了すると、自動的にスケジュールが再設定されます。

PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
pipeline_schedule_id整数はいパイプラインスケジュールのID。
activeブール値いいえパイプラインスケジュールをアクティブにします。falseが設定されている場合、パイプラインスケジュールは最初に非アクティブ化されます。
cron_timezone文字列いいえActiveSupport::TimeZone（例：Pacific Time (US & Canada)）またはTZInfo::Timezone（例：America/Los_Angeles）でサポートされているタイムゾーン。
cron文字列いいえCronスケジュール（例：0 1 * * *）。
description文字列いいえパイプラインスケジュールの説明。
ref文字列いいえパイプラインをトリガーするブランチまたはタグ名。短いrefs（例：main）と完全なrefs（例：refs/heads/mainまたはrefs/tags/main）の両方を受け入れます。短いrefsは自動的に完全なrefsに展開されますが、refがあいまいな場合、リクエストは拒否されます。
inputsハッシュいいえパイプラインスケジュールに渡すinputsの配列。各入力には、nameとvalueが含まれています。既存の入力を削除するには、nameフィールドを含め、destroyをtrueに設定します。値には、文字列、配列、数値、またはブール値を指定できます。

リクエスト例:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13" \
  --form "cron=0 2 * * *"

レスポンス例:

{
    "id": 13,
    "description": "Test schedule pipeline",
    "ref": "refs/heads/main",
    "cron": "0 2 * * *",
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T17:00:00.000Z",
    "active": true,
    "created_at": "2017-05-19T13:31:08.849Z",
    "updated_at": "2017-05-19T13:44:16.135Z",
    "last_pipeline": {
        "id": 332,
        "sha": "0e788619d0b5ec17388dffb973ecd505946156db",
        "ref": "refs/heads/main",
        "status": "pending"
    },
    "owner": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
        "web_url": "https://gitlab.example.com/root"
    }
}

inputsを使用したリクエスト例:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13" \
  --form "cron=0 2 * * *" \
  --form "inputs[][name]=deploy_strategy" \
  --form "inputs[][value]=rolling" \
  --form "inputs[][name]=existing_input" \
  --form "inputs[][_destroy]=true"

パイプラインスケジュールの所有権を取得

プロジェクトのパイプラインスケジュールのオーナーを更新します。

POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/take_ownership
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
pipeline_schedule_id整数はいパイプラインスケジュールのID。
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/take_ownership"
{
    "id": 13,
    "description": "Test schedule pipeline",
    "ref": "refs/heads/main",
    "cron": "0 2 * * *",
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T17:00:00.000Z",
    "active": true,
    "created_at": "2017-05-19T13:31:08.849Z",
    "updated_at": "2017-05-19T13:46:37.468Z",
    "last_pipeline": {
        "id": 332,
        "sha": "0e788619d0b5ec17388dffb973ecd505946156db",
        "ref": "refs/heads/main",
        "status": "pending"
    },
    "owner": {
        "name": "shinya",
        "username": "maeda",
        "id": 50,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/8ca0a796a679c292e3a11da50f99e801?s=80&d=identicon",
        "web_url": "https://gitlab.example.com/maeda"
    }
}

パイプラインスケジュールを削除する

プロジェクトのパイプラインスケジュールを削除します。

DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
pipeline_schedule_id整数はいパイプラインスケジュールのID。
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13"
{
    "id": 13,
    "description": "Test schedule pipeline",
    "ref": "refs/heads/main",
    "cron": "0 2 * * *",
    "cron_timezone": "Asia/Tokyo",
    "next_run_at": "2017-05-19T17:00:00.000Z",
    "active": true,
    "created_at": "2017-05-19T13:31:08.849Z",
    "updated_at": "2017-05-19T13:46:37.468Z",
    "last_pipeline": {
        "id": 332,
        "sha": "0e788619d0b5ec17388dffb973ecd505946156db",
        "ref": "refs/heads/main",
        "status": "pending"
    },
    "owner": {
        "name": "shinya",
        "username": "maeda",
        "id": 50,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/8ca0a796a679c292e3a11da50f99e801?s=80&d=identicon",
        "web_url": "https://gitlab.example.com/maeda"
    }
}

スケジュールされたパイプラインをすぐに実行

新しいスケジュールされたパイプラインをトリガーします。これはすぐに実行されます。このパイプラインの次回のスケジュールされた実行には影響しません。

POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/play
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
pipeline_schedule_id整数はいパイプラインスケジュールのID。

リクエスト例:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/42/pipeline_schedules/1/play"

レスポンス例:

{
  "message": "201 Created"
}

パイプラインスケジュールの変数

新しいパイプラインスケジュール変数の作成

パイプラインスケジュールの新しい変数を作成します。

POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
key文字列はい変数のキー。255文字以下である必要があります。A-Z、a-z、0-9、および_のみが許可されています。
pipeline_schedule_id整数はいパイプラインスケジュールのID。
value文字列はい変数の値。
variable_type文字列いいえ変数の型。利用可能な型は、env_var（デフォルト）とfileです。
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables" \
  --form "key=NEW_VARIABLE" \
  --form "value=new value"
{
    "key": "NEW_VARIABLE",
    "variable_type": "env_var",
    "value": "new value"
}

パイプラインスケジュール変数の編集

パイプラインスケジュールの変数を更新します。

PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
key文字列はい変数のキー。
pipeline_schedule_id整数はいパイプラインスケジュールのID。
value文字列はい変数の値。
variable_type文字列いいえ変数の型。利用可能な型は、env_var（デフォルト）とfileです。
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE" \
  --form "value=updated value"
{
    "key": "NEW_VARIABLE",
    "value": "updated value",
    "variable_type": "env_var"
}

パイプラインスケジュール変数の削除

パイプラインスケジュールの変数を削除します。

DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
key文字列はい変数のキー。
pipeline_schedule_id整数はいパイプラインスケジュールのID。
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"
{
    "key": "NEW_VARIABLE",
    "value": "updated value"
}

トラブルシューティング

パイプラインスケジュールAPIを使用する際に、以下の問題が発生する可能性があります。

短いrefsが完全なrefsに展開される

短いrefを指定すると、完全なrefに自動的に展開されます。この動作は意図されたものであり、明示的なリソース識別を保証します。

APIは、短いrefs（mainなど）と完全なrefs（refs/heads/mainまたはrefs/tags/mainなど）の両方を受け入れます。

あいまいなrefs

次の場合、APIは短いrefを完全なrefに自動的に展開できません:

  • ブランチとタグの両方が、短いrefrefと同じ名前で存在します。
  • その名前のブランチまたはタグは存在しません。

この問題を解決するには、完全なrefを指定して、正しいリソースが識別されるようにします。