debian-mirror-gitlab/doc/api/pipeline_triggers.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

225 lines
7.6 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
stage: Verify
2021-09-04 01:27:46 +05:30
group: Pipeline Execution
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2020-10-24 23:57:45 +05:30
---
2022-07-23 23:45:48 +05:30
# Pipeline trigger tokens API **(FREE)**
2017-08-17 22:00:37 +05:30
2021-09-30 23:02:18 +05:30
You can read more about [triggering pipelines through the API](../ci/triggers/index.md).
2017-08-17 22:00:37 +05:30
2022-07-23 23:45:48 +05:30
## List project trigger tokens
2017-08-17 22:00:37 +05:30
2022-07-23 23:45:48 +05:30
Get a list of a project's pipeline trigger tokens.
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/triggers
```
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers"
2017-08-17 22:00:37 +05:30
```
```json
[
{
"id": 10,
"description": "my trigger",
"created_at": "2016-01-07T09:53:58.235Z",
"last_used": null,
"token": "6d056f63e50fe6f8c5f8f4aa10edb7",
"updated_at": "2016-01-07T09:53:58.235Z",
"owner": null
}
]
```
2021-11-11 11:23:49 +05:30
The trigger token is displayed in full if the trigger token was created by the authenticated
user. Trigger tokens created by other users are shortened to four characters.
2022-07-23 23:45:48 +05:30
## Get trigger token details
2017-08-17 22:00:37 +05:30
2022-07-23 23:45:48 +05:30
Get details of a project's pipeline trigger.
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/triggers/:trigger_id
```
| Attribute | Type | required | Description |
|--------------|---------|----------|--------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `trigger_id` | integer | yes | The trigger ID |
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5"
2017-08-17 22:00:37 +05:30
```
```json
{
"id": 10,
"description": "my trigger",
"created_at": "2016-01-07T09:53:58.235Z",
"last_used": null,
"token": "6d056f63e50fe6f8c5f8f4aa10edb7",
"updated_at": "2016-01-07T09:53:58.235Z",
"owner": null
}
```
2022-07-23 23:45:48 +05:30
## Create a trigger token
2017-08-17 22:00:37 +05:30
2022-07-23 23:45:48 +05:30
Create a pipeline trigger for a project.
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/triggers
```
| Attribute | Type | required | Description |
|---------------|---------|----------|--------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2017-08-17 22:00:37 +05:30
| `description` | string | yes | The trigger name |
2020-04-08 14:13:33 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers"
2017-08-17 22:00:37 +05:30
```
```json
{
"id": 10,
"description": "my trigger",
"created_at": "2016-01-07T09:53:58.235Z",
"last_used": null,
"token": "6d056f63e50fe6f8c5f8f4aa10edb7",
"updated_at": "2016-01-07T09:53:58.235Z",
"owner": null
}
```
2022-07-23 23:45:48 +05:30
## Update a project trigger token
2017-08-17 22:00:37 +05:30
2022-07-23 23:45:48 +05:30
Update a pipeline trigger token for a project.
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/triggers/:trigger_id
```
| Attribute | Type | required | Description |
|---------------|---------|----------|--------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `trigger_id` | integer | yes | The trigger ID |
2017-08-17 22:00:37 +05:30
| `description` | string | no | The trigger name |
2020-04-08 14:13:33 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form description="my description" "https://gitlab.example.com/api/v4/projects/1/triggers/10"
2017-08-17 22:00:37 +05:30
```
```json
{
"id": 10,
"description": "my trigger",
"created_at": "2016-01-07T09:53:58.235Z",
"last_used": null,
"token": "6d056f63e50fe6f8c5f8f4aa10edb7",
"updated_at": "2016-01-07T09:53:58.235Z",
"owner": null
}
```
2022-07-23 23:45:48 +05:30
## Remove a project trigger token
2017-08-17 22:00:37 +05:30
2022-07-23 23:45:48 +05:30
Remove a project's pipeline trigger token.
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/triggers/:trigger_id
```
| Attribute | Type | required | Description |
|----------------|---------|----------|--------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2020-05-24 23:13:21 +05:30
| `trigger_id` | integer | yes | The trigger ID |
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5"
2017-08-17 22:00:37 +05:30
```
2022-07-23 23:45:48 +05:30
## Trigger a pipeline with a token
Trigger a pipeline by using a pipeline [trigger token](../ci/triggers/index.md#create-a-trigger-token)
or a [CI/CD job token](../ci/jobs/ci_job_token.md) for authentication.
2022-11-25 23:54:43 +05:30
With a CI/CD job token, the [triggered pipeline is a multi-project pipeline](../ci/pipelines/downstream_pipelines.md#trigger-a-multi-project-pipeline-by-using-the-api).
2022-07-23 23:45:48 +05:30
The job that authenticates the request becomes associated with the upstream pipeline,
2022-10-11 01:57:18 +05:30
which is visible on the [pipeline graph](../ci/pipelines/downstream_pipelines.md#view-multi-project-pipelines-in-pipeline-graphs).
2022-07-23 23:45:48 +05:30
If you use a trigger token in a job, the job is not associated with the upstream pipeline.
```plaintext
POST /projects/:id/trigger/pipeline
```
Supported attributes:
| Attribute | Type | Required | Description |
|:------------|:---------------|:-----------------------|:---------------------|
| `id` | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `ref` | string | **{check-circle}** Yes | The branch or tag to run the pipeline on. |
| `token` | string | **{check-circle}** Yes | The trigger token or CI/CD job token. |
2022-11-25 23:54:43 +05:30
| `variables` | array | **{dotted-circle}** No | An [array of hashes](index.md#array-of-hashes) containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. |
2022-07-23 23:45:48 +05:30
Example request:
```shell
curl --request POST "https://gitlab.example.com/api/v4/projects/123/trigger/pipeline?token=2cb1840fb9dfc9fb0b7b1609cd29cb&ref=main"
```
Example response:
```json
{
"id": 257,
"iid": 118,
"project_id": 21,
"sha": "91e2711a93e5d9e8dddfeb6d003b636b25bf6fc9",
"ref": "main",
"status": "created",
"source": "trigger",
"created_at": "2022-03-31T01:12:49.068Z",
"updated_at": "2022-03-31T01:12:49.068Z",
"web_url": "http://127.0.0.1:3000/test-group/test-project/-/pipelines/257",
"before_sha": "0000000000000000000000000000000000000000",
"tag": false,
"yaml_errors": null,
"user": {
"id": 1,
"username": "root",
"name": "Administrator",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "http://127.0.0.1:3000/root"
},
"started_at": null,
"finished_at": null,
"committed_at": null,
"duration": null,
"queued_duration": null,
"coverage": null,
"detailed_status": {
"icon": "status_created",
"text": "created",
"label": "created",
"group": "created",
"tooltip": "created",
"has_details": true,
"details_path": "/test-group/test-project/-/pipelines/257",
"illustration": null,
"favicon": "/assets/ci_favicons/favicon_status_created-4b975aa976d24e5a3ea7cd9a5713e6ce2cd9afd08b910415e96675de35f64955.png"
}
}
```