diff options
Diffstat (limited to 'doc/api/jobs.md')
-rw-r--r-- | doc/api/jobs.md | 106 |
1 files changed, 49 insertions, 57 deletions
diff --git a/doc/api/jobs.md b/doc/api/jobs.md index a28acfbd1a1..a48168c8362 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -21,10 +21,10 @@ pagination is recommended when requesting consecutive pages of results. GET /projects/:id/jobs ``` -| Attribute | Type | Required | Description | -|-----------|--------------------------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `scope` | string **or** array of strings | **{dotted-circle}** No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | +| Attribute | Type | Required | Description | +|-----------|--------------------------------|----------|-------------| +| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `scope` | string **or** array of strings | No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | ```shell curl --globoff --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running" @@ -172,16 +172,22 @@ Get a list of jobs for a pipeline. By default, this request returns 20 results at a time because the API results [are paginated](rest/index.md#pagination) +This endpoint: + +- [Returns data for any pipeline](pipelines.md#get-a-single-pipeline) including [child pipelines](../ci/pipelines/downstream_pipelines.md#parent-child-pipelines). +- Does not return retried jobs in the response by default. +- Sorts jobs by ID in descending order (newest first). + ```plaintext GET /projects/:id/pipelines/:pipeline_id/jobs ``` -| Attribute | Type | Required | Description | -|-------------------|--------------------------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `pipeline_id` | integer | **{check-circle}** Yes | ID of a pipeline. Can also be obtained in CI jobs via the [predefined CI variable](../ci/variables/predefined_variables.md) `CI_PIPELINE_ID`. | -| `scope` | string **or** array of strings | **{dotted-circle}** No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | -| `include_retried` | boolean | **{dotted-circle}** No | Include retried jobs in the response. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/272627) in GitLab 13.9. | +| Attribute | Type | Required | Description | +|-------------------|--------------------------------|----------|-------------| +| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `pipeline_id` | integer | Yes | ID of a pipeline. Can also be obtained in CI jobs via the [predefined CI variable](../ci/variables/predefined_variables.md) `CI_PIPELINE_ID`. | +| `scope` | string **or** array of strings | No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | +| `include_retried` | boolean | No | Include retried jobs in the response. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/272627) in GitLab 13.9. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/6/jobs?scope[]=pending&scope[]=running" @@ -323,16 +329,6 @@ Example of response ] ``` -In GitLab 13.3 and later, this endpoint [returns data for any pipeline](pipelines.md#get-a-single-pipeline) -including [child pipelines](../ci/pipelines/downstream_pipelines.md#parent-child-pipelines). - -In GitLab 13.5 and later, this endpoint does not return retried jobs in the response -by default. Additionally, jobs are sorted by ID in descending order (newest first). -In earlier GitLab versions, jobs are sorted by ID in ascending order (oldest first). - -In GitLab 13.9 and later, this endpoint can include retried jobs in the response -with `include_retried` set to `true`. - ## List pipeline trigger jobs Get a list of trigger jobs for a pipeline. @@ -341,11 +337,11 @@ Get a list of trigger jobs for a pipeline. GET /projects/:id/pipelines/:pipeline_id/bridges ``` -| Attribute | Type | Required | Description | -|---------------|--------------------------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `pipeline_id` | integer | **{check-circle}** Yes | ID of a pipeline. | -| `scope` | string **or** array of strings | **{dotted-circle}** No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | +| Attribute | Type | Required | Description | +|---------------|--------------------------------|----------|-------------| +| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `pipeline_id` | integer | Yes | ID of a pipeline. | +| `scope` | string **or** array of strings | No | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `waiting_for_resource`, or `manual`. All jobs are returned if `scope` is not provided. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/6/bridges?scope[]=pending&scope[]=running" @@ -425,8 +421,6 @@ Example of response ## Get job token's job -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51727) in GitLab 13.10. - Retrieve the job that generated a job token. ```plaintext @@ -505,8 +499,6 @@ Example of response ## Get GitLab agent by `CI_JOB_TOKEN` **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324269) in GitLab 13.11. - Retrieve the job that generated the `CI_JOB_TOKEN`, along with a list of allowed [agents](../user/clusters/agent/index.md). @@ -516,9 +508,9 @@ GET /job/allowed_agents Supported attributes: -| Attribute | Type | Required | Description | -|----------------|----------|------------------------|-------------| -| `CI_JOB_TOKEN` | string | **{check-circle}** Yes | Token value associated with the GitLab-provided `CI_JOB_TOKEN` variable. | +| Attribute | Type | Required | Description | +|----------------|--------|----------|-------------| +| `CI_JOB_TOKEN` | string | Yes | Token value associated with the GitLab-provided `CI_JOB_TOKEN` variable. | Example request: @@ -584,10 +576,10 @@ Get a single job of a project GET /projects/:id/jobs/:job_id ``` -| Attribute | Type | Required | Description | -|-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | **{check-circle}** Yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|----------|-------------| +| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `job_id` | integer | Yes | ID of a job. | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8" @@ -665,10 +657,10 @@ Get a log (trace) of a specific job of a project: GET /projects/:id/jobs/:job_id/trace ``` -| Attribute | Type | Required | Description | -|-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | **{check-circle}** Yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|----------|-------------| +| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `job_id` | integer | Yes | ID of a job. | ```shell curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/trace" @@ -689,10 +681,10 @@ Cancel a single job of a project POST /projects/:id/jobs/:job_id/cancel ``` -| Attribute | Type | Required | Description | -|-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | **{check-circle}** Yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|----------|-------------| +| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `job_id` | integer | Yes | ID of a job. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/cancel" @@ -743,10 +735,10 @@ Retry a single job of a project POST /projects/:id/jobs/:job_id/retry ``` -| Attribute | Type | Required | Description | -|-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | **{check-circle}** Yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|----------|-------------| +| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `job_id` | integer | Yes | ID of a job. | ```shell curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/retry" @@ -799,10 +791,10 @@ POST /projects/:id/jobs/:job_id/erase Parameters -| Attribute | Type | Required | Description | -|-----------|----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | **{check-circle}** Yes | ID of a job. | +| Attribute | Type | Required | Description | +|-----------|----------------|----------|-------------| +| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `job_id` | integer | Yes | ID of a job. | Example of request @@ -860,11 +852,11 @@ For a job in manual status, trigger an action to start the job. POST /projects/:id/jobs/:job_id/play ``` -| Attribute | Type | Required | Description | -|----------------------------|-----------------|------------------------|-------------| -| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | **{check-circle}** Yes | ID of a job. | -| `job_variables_attributes` | array of hashes | **{dotted-circle}** No | An array containing the custom variables available to the job. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/37267) GitLab 14.9. | +| Attribute | Type | Required | Description | +|----------------------------|-----------------|----------|-------------| +| `id` | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). | +| `job_id` | integer | Yes | ID of a job. | +| `job_variables_attributes` | array of hashes | No | An array containing the custom variables available to the job. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/37267) GitLab 14.9. | Example request: |