diff options
Diffstat (limited to 'doc/api/pipeline_triggers.md')
| -rw-r--r-- | doc/api/pipeline_triggers.md | 97 |
1 files changed, 86 insertions, 11 deletions
diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index 5472e5bc334..8db071bf811 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -4,13 +4,13 @@ group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Pipeline triggers API **(FREE)** +# Pipeline trigger tokens API **(FREE)** You can read more about [triggering pipelines through the API](../ci/triggers/index.md). -## List project triggers +## List project trigger tokens -Get a list of project's build triggers. +Get a list of a project's pipeline trigger tokens. ```plaintext GET /projects/:id/triggers @@ -41,9 +41,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a 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. -## Get trigger details +## Get trigger token details -Get details of project's build trigger. +Get details of a project's pipeline trigger. ```plaintext GET /projects/:id/triggers/:trigger_id @@ -70,9 +70,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a } ``` -## Create a project trigger +## Create a trigger token -Create a trigger for a project. +Create a pipeline trigger for a project. ```plaintext POST /projects/:id/triggers @@ -100,9 +100,9 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ } ``` -## Update a project trigger +## Update a project trigger token -Update a trigger for a project. +Update a pipeline trigger token for a project. ```plaintext PUT /projects/:id/triggers/:trigger_id @@ -131,9 +131,9 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ } ``` -## Remove a project trigger +## Remove a project trigger token -Remove a project's build trigger. +Remove a project's pipeline trigger token. ```plaintext DELETE /projects/:id/triggers/:trigger_id @@ -147,3 +147,78 @@ DELETE /projects/:id/triggers/:trigger_id ```shell curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5" ``` + +## 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. + +With a CI/CD job token, the [triggered pipeline is a multi-project pipeline](../ci/jobs/ci_job_token.md#trigger-a-multi-project-pipeline-by-using-a-cicd-job-token). +The job that authenticates the request becomes associated with the upstream pipeline, +which is visible on the [pipeline graph](../ci/pipelines/multi_project_pipelines.md#multi-project-pipeline-visualization). + +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. | +| `variables` | array | **{dotted-circle}** No | An array 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`. | + +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" + } +} +``` |