Help us learn about your current experience with the documentation. Take the survey.

Pipeline schedules API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用此 API 与 pipeline schedules 进行交互。

获取所有流水线调度

获取项目的流水线调度列表。

GET /projects/:id/pipeline_schedules

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径
`scope`	string	否	流水线调度的范围，必须是以下之一：`active`、`inactive`

curl --header "PRIVATE-TOKEN: <your_access_token>" "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`	integer/string	是	项目的 ID 或 URL 编码路径
`pipeline_schedule_id`	integer	是	流水线调度 ID

curl --header "PRIVATE-TOKEN: <your_access_token>" "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`	integer/string	是	项目的 ID 或 URL 编码路径。
`pipeline_schedule_id`	integer	是	流水线调度 ID。

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "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`	string	是	cron 调度，例如：`0 1 * * *`。
`description`	string	是	流水线调度的描述。
`id`	integer/string	是	项目的 ID 或 URL 编码路径。
`ref`	string	是	触发的分支或标签名称。接受短版本（例如：`main`）和完整版本（例如：`refs/heads/main` 或 `refs/tags/main`）。如果提供短版本，会自动扩展为完整版本，但如果 ref 是模糊的，则会被拒绝
`active`	boolean	否	流水线调度的激活状态。如果设置为 false，流水线调度初始为未激活状态（默认：`true`）。
`cron_timezone`	string	否	`ActiveSupport::TimeZone` 支持的时区，例如：`Pacific Time (US & Canada)`（默认：`UTC`）。
`inputs`	hash	否	传递给流水线调度的 inputs 数组。每个 input 包含一个 `name` 和 `value`。值可以是字符串、数组、数字或布尔值。

示例请求：

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

示例响应：

{
    "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>" \
     --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" \
     "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules"

编辑流水线调度

更新项目的流水线调度。更新完成后，会自动重新调度。

PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径。
`pipeline_schedule_id`	integer	是	流水线调度 ID。
`active`	boolean	否	流水线调度的激活状态。如果设置为 false，流水线调度初始为未激活状态。
`cron_timezone`	string	否	`ActiveSupport::TimeZone` 支持的时区（例如 `Pacific Time (US & Canada)`），或 `TZInfo::Timezone`（例如 `America/Los_Angeles`）。
`cron`	string	否	cron 调度，例如：`0 1 * * *`。
`description`	string	否	流水线调度的描述。
`ref`	string	否	触发的分支或标签名称。接受短版本（例如：`main`）和完整版本（例如：`refs/heads/main` 或 `refs/tags/main`）。如果提供短版本，会自动扩展为完整版本，但如果 ref 是模糊的，则会被拒绝
`inputs`	hash	否	传递给流水线调度的 inputs 数组。每个 input 包含一个 `name` 和 `value`。要删除现有的 input，包含 `name` 字段并将 `destroy` 设置为 `true`。值可以是字符串、数组、数字或布尔值。

示例请求：

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

接管流水线调度

更新项目的流水线调度所有者。

POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/take_ownership

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径
`pipeline_schedule_id`	integer	是	流水线调度 ID

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "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`	integer/string	是	项目的 ID 或 URL 编码路径
`pipeline_schedule_id`	integer	是	流水线调度 ID

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "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`	integer/string	是	项目的 ID 或 URL 编码路径
`pipeline_schedule_id`	integer	是	流水线调度 ID

示例请求：

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "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`	integer/string	是	项目的 ID 或 URL 编码路径
`key`	string	是	变量的 `key`；不能超过 255 个字符；只允许 `A-Z`、`a-z`、`0-9` 和 `_`
`pipeline_schedule_id`	integer	是	流水线调度 ID
`value`	string	是	变量的 `value`
`variable_type`	string	否	变量的类型。可用类型有：`env_var`（默认）和 `file`

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "key=NEW_VARIABLE" \
     --form "value=new value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables"

{
    "key": "NEW_VARIABLE",
    "variable_type": "env_var",
    "value": "new value"
}

编辑流水线调度变量

更新流水线调度的变量。

PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径
`key`	string	是	变量的 `key`
`pipeline_schedule_id`	integer	是	流水线调度 ID
`value`	string	是	变量的 `value`
`variable_type`	string	否	变量的类型。可用类型有：`env_var`（默认）和 `file`

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "value=updated value" \
     "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"

{
    "key": "NEW_VARIABLE",
    "value": "updated value",
    "variable_type": "env_var"
}

删除流水线调度变量

删除流水线调度的变量。

DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径
`key`	string	是	变量的 `key`
`pipeline_schedule_id`	integer	是	流水线调度 ID

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE"

{
    "key": "NEW_VARIABLE",
    "value": "updated value"
}