CI jobs

Use this API to interact with CI/CD jobs.

Retrieve a job by job token

GET /api/v4/job

Retrieves a job that was generated by a specified job token.

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiJob
`400`	Bad request	—
`401`	Unauthorized	—
`404`	Not found	—

List all jobs for a project

GET /api/v4/projects/{id}/jobs

Lists all jobs for a specified project. By default, this request returns 20 results at a time because the API results are paginated.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`scope` Query	Array of strings	The scope of builds to show Example: `["pending","running"]`
`ref` Query	String	The branch name (ref) to filter jobs by Example: `feature-branch`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiJob
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Retrieve a job

GET /api/v4/projects/{id}/jobs/{job_id}

Retrieves a job with the specified job ID.

Parameters

Name	Type	Description
`job_id` Path, required	Integer	The ID of a job Example: `88`
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiJob
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Cancel a job

POST /api/v4/projects/{id}/jobs/{job_id}/cancel

Cancels a specified job in a project.

Parameters

Name	Type	Description
`job_id` Path, required	Integer	The ID of a job Example: `88`
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Request body (application/json)

Property	Type	Description
`force`	Boolean	Force cancellation for a job with a state of `canceling` Example: `true`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCiJob
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Erase a job

POST /api/v4/projects/{id}/jobs/{job_id}/erase

Erases a specified job in a project. This removes job artifacts and the job log.

Parameters

Name	Type	Description
`job_id` Path, required	Integer	The ID of a build Example: `88`
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCiJob
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`409`	Conflict	—

Run a job

POST /api/v4/projects/{id}/jobs/{job_id}/play

Runs a specified job. For a job in manual status, triggers an action to start the job.

Parameters

Name	Type	Description
`job_id` Path, required	Integer	The ID of a Job Example: `88`
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Request body (application/json)

Property	Type	Description
`job_inputs`	Object	Input values for the job Example: `{"environment":"production"}`
`job_variables_attributes`	Array of objects	User defined variables that will be included when running the job
`job_variables_attributes[].key` Required	String	The name of the variable Example: `foo`
`job_variables_attributes[].value` Required	String	The value of the variable Example: `bar`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiJobBasic
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Retry a job

POST /api/v4/projects/{id}/jobs/{job_id}/retry

Retries a specified job in a project.

Parameters

Name	Type	Description
`job_id` Path, required	Integer	The ID of a job Example: `88`
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Request body (application/json)

Property	Type	Description
`inputs`	Object	Input values for the job Example: `{"environment":"production"}`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCiJob
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Get the runtime environment key for a job

GET /api/v4/projects/{id}/jobs/{job_id}/runtime_environment_key

Retrieves the runtime environment key linked to a job, if the job is resuming a suspended environment.

Parameters

Name	Type	Description
`job_id` Path, required	Integer	The ID of a job Example: `88`
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiRuntimeEnvironmentKey
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Get a trace of a specific job of a project

GET /api/v4/projects/{id}/jobs/{job_id}/trace

Retrieves a log file for a job.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`job_id` Path, required	Integer	The ID of a job Example: `88`
`byte_offset` Query	Integer	Byte offset to start reading from Minimum: `0` Example: `0`
`byte_limit` Query	Integer	Maximum number of bytes to return Maximum: `512000` Minimum: `1` Example: `51200`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCiJob
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCiJob

Property	Type	Description
`allow_failure`	Boolean	—
`archived`	Boolean	Example: `false`
`artifacts`	Array of APIEntitiesCiJobArtifact	—
`artifacts_expire_at`	String (date-time)	Example: `2016-01-19T09:05:50.355Z`
`artifacts_file`	APIEntitiesCiJobArtifactFile	—
`commit`	APIEntitiesCommit	—
`coverage`	Number (float)	Example: `98.29`
`created_at`	String (date-time)	Example: `2015-12-24T15:51:21.880Z`
`duration`	Number (float)	Time spent running Example: `0.465`
`erased_at`	String (date-time)	Example: `2015-12-24T18:00:29.728Z`
`failure_reason`	String	Example: `script_failure`
`finished_at`	String (date-time)	Example: `2015-12-24T17:54:31.198Z`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `deploy_to_production`
`pipeline`	APIEntitiesCiPipelineBasic	—
`project`	Object	—
`project.ci_job_token_scope_enabled`	String	Example: `false`
`queued_duration`	Number (float)	Time spent enqueued Example: `0.123`
`ref`	String	Example: `main`
`runner`	APIEntitiesCiRunner	—
`runner_manager`	APIEntitiesCiRunnerManager	—
`stage`	String	Example: `deploy`
`started_at`	String (date-time)	Example: `2015-12-24T17:54:30.733Z`
`status`	String	Example: `waiting_for_resource`
`tag`	Boolean	—
`tag_list`	Array of strings	Example: `["ubuntu18","docker runner"]`
`user`	APIEntitiesUser	—
`web_url`	String	Example: `https://example.com/foo/bar/-/jobs/1`

APIEntitiesCiJobArtifact

Property	Type	Description
`file_format`	String	Allowed values: `raw`, `zip`, `gzip` Example: `zip`
`file_type`	String	Allowed values: `archive`, `metadata`, `trace`, `junit`, `sast`, `dependency_scanning`, `container_scanning`, `dast`, `codequality`, `license_scanning`, `performance`, `metrics`, `metrics_referee`, `network_referee`, `lsif`, `dotenv`, `cobertura`, `terraform`, `accessibility`, `cluster_applications`, `secret_detection`, `requirements`, `coverage_fuzzing`, `browser_performance`, `load_performance`, `api_fuzzing`, `cluster_image_scanning`, `cyclonedx`, `requirements_v2`, `annotations`, `repository_xray`, `jacoco`, `sarif` Example: `archive`
`filename`	String	Example: `artifacts.zip`
`size`	Integer	Example: `1000`

APIEntitiesCiJobArtifactFile

Property	Type	Description
`filename`	String	Example: `artifacts.zip`
`size`	Integer	Example: `1000`

APIEntitiesCiJobBasic

Property	Type	Description
`allow_failure`	Boolean	—
`commit`	APIEntitiesCommit	—
`coverage`	Number (float)	Example: `98.29`
`created_at`	String (date-time)	Example: `2015-12-24T15:51:21.880Z`
`duration`	Number (float)	Time spent running Example: `0.465`
`erased_at`	String (date-time)	Example: `2015-12-24T18:00:29.728Z`
`failure_reason`	String	Example: `script_failure`
`finished_at`	String (date-time)	Example: `2015-12-24T17:54:31.198Z`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `deploy_to_production`
`pipeline`	APIEntitiesCiPipelineBasic	—
`project`	Object	—
`project.ci_job_token_scope_enabled`	String	Example: `false`
`queued_duration`	Number (float)	Time spent enqueued Example: `0.123`
`ref`	String	Example: `main`
`stage`	String	Example: `deploy`
`started_at`	String (date-time)	Example: `2015-12-24T17:54:30.733Z`
`status`	String	Example: `waiting_for_resource`
`tag`	Boolean	—
`user`	APIEntitiesUser	—
`web_url`	String	Example: `https://example.com/foo/bar/-/jobs/1`

APIEntitiesCiPipelineBasic

Property	Type	Description
`created_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`id`	Integer (int64)	Example: `1`
`iid`	Integer	Example: `2`
`project_id`	Integer (int64)	Example: `3`
`ref`	String	Example: `feature-branch`
`sha`	String	Example: `0ec9e58fdfca6cdd6652c083c9edb53abc0bad52`
`source`	String	Example: `push`
`status`	String	Example: `success`
`updated_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`web_url`	String	Example: `https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61`

APIEntitiesCiRunner

Property	Type	Description
`active`	Boolean	Example: `true`
`created_at`	String (date-time)	Example: `2025-05-03T00:00:00.000Z`
`created_by`	APIEntitiesUserBasic	—
`description`	String	Example: `test-1-20150125`
`id`	Integer (int64)	Example: `8`
`ip_address`	String	Example: `127.0.0.1`
`is_shared`	Boolean	Example: `true`
`job_execution_status`	String	Allowed values: `active`, `idle` Example: `idle`
`name`	String	Example: `test`
`online`	Boolean	Example: `true`
`paused`	Boolean	Example: `false`
`runner_type`	String	Allowed values: `instance_type`, `group_type`, `project_type` Example: `instance_type`
`status`	String	Example: `online`

APIEntitiesCiRunnerManager

Property	Type	Description
`architecture`	String	Example: `amd64`
`contacted_at`	String	Example: `2023-10-24T01:27:06.549Z`
`created_at`	String	Example: `2023-10-24T01:27:06.549Z`
`id`	Integer (int64)	Example: `8`
`ip_address`	String	Example: `127.0.0.1`
`job_execution_status`	String	Allowed values: `active`, `idle` Example: `idle`
`platform`	String	Example: `linux`
`revision`	String	Example: `91a27b2a`
`status`	String	Example: `online`
`system_id`	String	Example: `runner-1`
`version`	String	Example: `16.11.0`

APIEntitiesCiRuntimeEnvironmentKey

Property	Type	Description
`runtime_environment_key`	String	Example: `42/s_machineid/data`

APIEntitiesCommit

Property	Type	Description
`author_email`	String	Example: `john@example.com`
`author_name`	String	Example: `John Smith`
`authored_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committed_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committer_email`	String	Example: `jack@example.com`
`committer_name`	String	Example: `Jack Smith`
`created_at`	String (date-time)	Example: `2017-07-26T11:08:53.000+02:00`
`extended_trailers`	Object	Example: `{"Signed-off-by":["John Doe \u003cjohndoe@gitlab.com\u003e","Jane Doe \u003cjanedoe@gitlab.com\u003e"]}`
`id`	String	Example: `2695effb5807a22ff3d138d593fd856244e155e7`
`message`	String	Example: `Initial commit`
`parent_ids`	Array of strings	Example: `["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]`
`short_id`	String	Example: `2695effb`
`title`	String	Example: `Initial commit`
`trailers`	Object	Example: `{"Merged-By":"Jane Doe janedoe@gitlab.com"}`
`web_url`	String	Example: `https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746`

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesUser

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`bio`	String	—
`bot`	Boolean	—
`created_at`	String	—
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`discord`	String	—
`followers`	String	—
`following`	String	—
`github`	String	—
`id`	Integer (int64)	Example: `1`
`is_followed`	String	—
`job_title`	String	—
`linkedin`	String	—
`local_time`	String	—
`location`	String	—
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`organization`	String	—
`pronouns`	String	—
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`twitter`	String	—
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`
`website_url`	String	—
`work_information`	String	—

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

Retrieve a job by job token

List all jobs for a project

Retrieve a job

Cancel a job

Erase a job

Run a job

Retry a job

Get the runtime environment key for a job

Get a trace of a specific job of a project

Schemas

APIEntitiesCiJob

APIEntitiesCiJobArtifact

APIEntitiesCiJobArtifactFile

APIEntitiesCiJobBasic

APIEntitiesCiPipelineBasic

APIEntitiesCiRunner

APIEntitiesCiRunnerManager

APIEntitiesCiRuntimeEnvironmentKey

APIEntitiesCommit

APIEntitiesCustomAttribute

APIEntitiesUser

APIEntitiesUserBasic

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC Compliance Report

Thank you

Error