Skip to content

G
gitlab-ce
Commit 416f756f authored by Marcel Amirault's avatar Marcel Amirault
Browse files
Options

Merge branch 'docs/update-api-jobs' into 'master' 

Update doc/api/jobs.md

See merge request gitlab-org/gitlab!79115
parents a9c82335 57fc70d9
Hide whitespace changes
Inline Side-by-side
Showing with 46 additions and 42 deletions
doc/api/jobs.md
View file @ 416f756f
...@@ -10,14 +10,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w ...@@ -10,14 +10,16 @@ info: To determine the technical writer assigned to the Stage/Group associated w
Get a list of jobs in a project. Jobs are sorted in descending order of their IDs. Get a list of jobs in a project. Jobs are sorted in descending order of their IDs.
By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination)
```plaintext ```plaintext
GET /projects/:id/jobs GET /projects/:id/jobs
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|-----------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |-----------|--------------------------------|------------------------|-------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `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`, or `manual`. All jobs are returned if `scope` is not provided. | | `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`, or `manual`. All jobs are returned if `scope` is not provided. |
```shell ```shell
curl --globoff --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running" curl --globoff --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running"
...@@ -155,16 +157,18 @@ Example of response ...@@ -155,16 +157,18 @@ Example of response
Get a list of jobs for a pipeline. Get a list of jobs for a pipeline.
By default, this request returns 20 results at a time because the API results [are paginated](index.md#pagination)
```plaintext ```plaintext
GET /projects/:id/pipelines/:pipeline_id/jobs GET /projects/:id/pipelines/:pipeline_id/jobs
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|-------------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |-------------------|--------------------------------|------------------------|-------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `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`. | | `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 | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | | `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`, 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. | | `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. |
```shell ```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/6/jobs?scope[]=pending&scope[]=running" curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/6/jobs?scope[]=pending&scope[]=running"
...@@ -316,11 +320,11 @@ Get a list of bridge jobs for a pipeline. ...@@ -316,11 +320,11 @@ Get a list of bridge jobs for a pipeline.
GET /projects/:id/pipelines/:pipeline_id/bridges GET /projects/:id/pipelines/:pipeline_id/bridges
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|---------------|--------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |---------------|--------------------------------|------------------------|-------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `pipeline_id` | integer | yes | ID of a pipeline. | | `pipeline_id` | integer | **{check-circle}** 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`, or `manual`. All jobs are returned if `scope` is not provided. | | `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`, or `manual`. All jobs are returned if `scope` is not provided. |
```shell ```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/6/bridges?scope[]=pending&scope[]=running" curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/6/bridges?scope[]=pending&scope[]=running"
...@@ -483,9 +487,9 @@ GET /job/allowed_agents ...@@ -483,9 +487,9 @@ GET /job/allowed_agents
Supported attributes: Supported attributes:
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|:------------ |:---------|:---------|:----------------------| |----------------|----------|------------------------|-------------|
| `CI_JOB_TOKEN` | string | yes | Token value associated with the GitLab-provided `CI_JOB_TOKEN` variable. | | `CI_JOB_TOKEN` | string | **{check-circle}** Yes | Token value associated with the GitLab-provided `CI_JOB_TOKEN` variable. |
Example request: Example request:
...@@ -558,10 +562,10 @@ Get a single job of a project ...@@ -558,10 +562,10 @@ Get a single job of a project
GET /projects/:id/jobs/:job_id GET /projects/:id/jobs/:job_id
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |-----------|----------------|------------------------|-------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id` | integer | yes | ID of a job. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. |
```shell ```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8" curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8"
...@@ -635,10 +639,10 @@ Get a log (trace) of a specific job of a project: ...@@ -635,10 +639,10 @@ Get a log (trace) of a specific job of a project:
GET /projects/:id/jobs/:job_id/trace GET /projects/:id/jobs/:job_id/trace
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |-----------|----------------|------------------------|-------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id` | integer | yes | ID of a job. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. |
```shell ```shell
curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/trace" curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/trace"
...@@ -659,10 +663,10 @@ Cancel a single job of a project ...@@ -659,10 +663,10 @@ Cancel a single job of a project
POST /projects/:id/jobs/:job_id/cancel POST /projects/:id/jobs/:job_id/cancel
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |-----------|----------------|------------------------|-------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id` | integer | yes | ID of a job. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. |
```shell ```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/cancel" curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/cancel"
...@@ -709,10 +713,10 @@ Retry a single job of a project ...@@ -709,10 +713,10 @@ Retry a single job of a project
POST /projects/:id/jobs/:job_id/retry POST /projects/:id/jobs/:job_id/retry
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |-----------|----------------|------------------------|-------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id` | integer | yes | ID of a job. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. |
```shell ```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/retry" curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/retry"
...@@ -761,10 +765,10 @@ POST /projects/:id/jobs/:job_id/erase ...@@ -761,10 +765,10 @@ POST /projects/:id/jobs/:job_id/erase
Parameters Parameters
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |-----------|----------------|------------------------|-------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id` | integer | yes | ID of a job. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. |
Example of request Example of request
...@@ -818,10 +822,10 @@ Triggers a manual action to start a job. ...@@ -818,10 +822,10 @@ Triggers a manual action to start a job.
POST /projects/:id/jobs/:job_id/play POST /projects/:id/jobs/:job_id/play
``` ```
| Attribute | Type | Required | Description | | Attribute | Type | Required | Description |
|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| |-----------|----------------|------------------------|-------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. | | `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `job_id` | integer | yes | ID of a job. | | `job_id` | integer | **{check-circle}** Yes | ID of a job. |
```shell ```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/play" curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/play"
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7