Jobs

Use this API to run CI/CD jobs on a runner: request the next job, update its state, append to its log, and transfer its artifacts.

GitLab Runner uses these endpoints itself.

Request a job

POST /api/v4/jobs/request

Requests a job for a runner to execute.

Request body (application/json)

Property	Type	Description
`info`	Object	Runner’s metadata
`info.architecture`	String	Runner’s architecture
`info.config`	Object	Runner’s config
`info.config.gpus`	String	GPUs enabled
`info.executor`	String	Runner’s executor
`info.features`	Object	Runner’s features
`info.labels`	Object	Runner’s labels
`info.name`	String	Runner’s name
`info.platform`	String	Runner’s platform
`info.revision`	String	Runner’s revision
`info.version`	String	Runner’s version
`last_update`	String	Runner’s queue last_update token
`session`	Object	Runner’s session data
`session.authorization`	String	Session’s authorization
`session.certificate`	String	Session’s certificate
`session.url`	String	Session’s url
`system_id`	String	Runner’s system identifier
`token` Required	String	Runner’s authentication token

Responses

Code	Description	Schema
`201`	Job was scheduled	APIEntitiesCiJobRequestResponse
`204`	No job for Runner	—
`400`	Bad Request	—
`403`	Forbidden	—
`409`	Conflict	—
`422`	Runner is orphaned	—
`429`	Too Many Requests	—

Update a job

PUT /api/v4/jobs/{id}

Parameters

Name	Type	Description
`id` Path, required	Integer	Job’s ID

Request body (application/json)

Property	Type	Description
`checksum`	String	Job’s trace CRC32 checksum
`exit_code`	Integer	Job’s exit code
`failure_reason`	String	Job’s failure_reason
`output`	Object	Build log state
`output.bytesize`	Integer	Job’s trace size in bytes
`output.checksum`	String	Job’s trace CRC32 checksum
`runtime_environment_key`	String	Runtime environment key emitted by the runner on job suspension Maximum length: `512`
`state`	String	Job’s status: running, success, failed
`token` Required	String	Job’s authentication token

Responses

Code	Description	Schema
`200`	Job was updated	—
`202`	Update accepted	—
`400`	Unknown parameters	—
`403`	Forbidden	—
`404`	Not Found	—
`409`	Conflict	—
`429`	Too Many Requests	—

Download job artifacts

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

Downloads artifacts for a specified job.

Parameters

Name	Type	Description
`id` Path, required	Integer	Job’s ID
`token` Query	String	Job’s authentication token
`direct_download` Query	Boolean	Perform direct download from remote storage instead of proxying artifacts Default: `false`

Responses

Code	Description	Schema
`200`	Download allowed	String (binary) (`application/octet-stream`)
`302`	Found	String (binary) (`application/octet-stream`)
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Artifact not found	—
`429`	Too Many Requests	—

Upload job artifacts

POST /api/v4/jobs/{id}/artifacts

Uploads artifacts for a specified job.

Parameters

Name	Type	Description
`id` Path, required	Integer	Job’s ID

Request body (multipart/form-data)

Property	Type	Description
`accessibility`	String	Specify accessibility level of artifact private/public
`artifact_format`	String	The format of artifact Allowed values: `raw`, `zip`, `gzip` Default: `zip`
`artifact_type`	String	The type of artifact 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` Default: `archive`
`expire_in`	String	Specify when artifact should expire
`file` Required	String (binary)	The artifact file to store (generated by Multipart middleware)
`metadata`	String (binary)	The artifact metadata to store (generated by Multipart middleware)
`token`	String	Job’s authentication token

Responses

Code	Description	Schema
`201`	Created	—
`400`	Bad request	—
`403`	Forbidden	—
`404`	Not Found	—
`405`	Artifacts support not enabled	—
`413`	File too large	—
`429`	Too Many Requests	—

Authorize artifacts upload

POST /api/v4/jobs/{id}/artifacts/authorize

Authorizes uploading artifacts for a specified job.

Parameters

Name	Type	Description
`id` Path, required	Integer	Job’s ID

Request body (application/json)

Property	Type	Description
`artifact_type`	String	The type of artifact 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` Default: `archive`
`filesize`	Integer	Size of artifact file
`token`	String	Job’s authentication token

Responses

Code	Description	Schema
`200`	Upload allowed	—
`400`	Bad Request	—
`403`	Forbidden	—
`404`	Not Found	—
`405`	Artifacts support not enabled	—
`413`	File too large	—
`429`	Too Many Requests	—

Append a patch to the job trace

PATCH /api/v4/jobs/{id}/trace

Parameters

Name	Type	Description
`id` Path, required	Integer	Job’s ID

Request body (application/json)

Property	Type	Description
`debug_trace`	Boolean	Enable or disable the debug trace
`token`	String	Job’s authentication token

Responses

Code	Description	Schema
`202`	Trace was patched	—
`400`	Missing Content-Range header	—
`403`	Forbidden	—
`404`	Not Found	—
`416`	Range not satisfiable	—
`429`	Too Many Requests	—

List all jobs processed by a runner

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

Lists all jobs that are being processed or were processed by a specified runner. The list of jobs is limited to projects where the user has the Reporter, Developer, Maintainer, or Owner role.

Parameters

Name	Type	Description
`id` Path, required	Integer	The ID of a runner
`system_id` Query	String	System ID associated with the runner manager
`status` Query	String	Status of the job Allowed values: `created`, `waiting_for_resource`, `preparing`, `waiting_for_callback`, `pending`, `running`, `success`, `failed`, `canceling`, `canceled`, `skipped`, `manual`, `scheduled`
`order_by` Query	String	Order by `id` Allowed values: `id`
`sort` Query	String	Sort by `asc` or `desc` order. Specify `order_by` as well, including for `id` Allowed values: `asc`, `desc` Default: `desc`
`cursor` Query	String	Cursor for obtaining the next set of records
`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	APIEntitiesCiJobBasicWithProject
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	No access granted	—
`404`	Runner not found	—

Schemas

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

APIEntitiesCiJobBasicWithProject

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`	APIEntitiesProjectIdentity	—
`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`

APIEntitiesCiJobRequestArtifacts

Property	Type	Description
`artifact_format`	String	—
`artifact_type`	String	—
`exclude`	String	—
`expire_in`	String	—
`name`	String	—
`paths`	String	—
`untracked`	String	—
`when`	String	—

APIEntitiesCiJobRequestCache

Property	Type	Description
`fallback_keys`	String	—
`key`	String	—
`paths`	String	—
`policy`	String	—
`untracked`	String	—
`when`	String	—

APIEntitiesCiJobRequestCredentials

Property	Type	Description
`password`	String	—
`type`	String	—
`url`	String	—
`username`	String	—

APIEntitiesCiJobRequestGitInfo

Property	Type	Description
`before_sha`	String	—
`depth`	String	—
`protected`	String	—
`ref`	String	—
`ref_type`	String	—
`refspecs`	String	—
`repo_object_format`	String	—
`repo_url`	String	—
`sha`	String	—

APIEntitiesCiJobRequestHook

Property	Type	Description
`name`	String	—
`script`	String	—

APIEntitiesCiJobRequestImage

Property	Type	Description
`entrypoint`	String	—
`executor_opts`	String	—
`name`	String	—
`ports`	APIEntitiesCiJobRequestPort	—
`pull_policy`	String	—

APIEntitiesCiJobRequestJobInfo

Property	Type	Description
`id`	String	—
`instance_id`	String	—
`instance_uuid`	String	—
`name`	String	—
`namespace_id`	String	—
`organization_id`	String	—
`pipeline_id`	String	—
`project_full_path`	String	—
`project_id`	String	—
`project_jobs_running_on_instance_runners_count`	String	—
`project_name`	String	—
`queue_depth`	String	—
`queue_size`	String	—
`root_namespace_id`	String	—
`scoped_user_id`	String	—
`stage`	String	—
`time_in_queue_seconds`	String	—
`user_id`	String	—

APIEntitiesCiJobRequestPort

Property	Type	Description
`name`	String	—
`number`	String	—
`protocol`	String	—

APIEntitiesCiJobRequestResponse

Property	Type	Description
`allow_git_fetch`	String	—
`artifacts`	APIEntitiesCiJobRequestArtifacts	—
`cache`	APIEntitiesCiJobRequestCache	—
`credentials`	APIEntitiesCiJobRequestCredentials	—
`dependencies`	String	—
`features`	String	—
`git_info`	APIEntitiesCiJobRequestGitInfo	—
`hooks`	APIEntitiesCiJobRequestHook	—
`id`	String	—
`image`	APIEntitiesCiJobRequestImage	—
`inputs`	String	—
`job_info`	APIEntitiesCiJobRequestJobInfo	—
`run`	String	—
`runner_info`	APIEntitiesCiJobRequestRunnerInfo	—
`secrets`	String	—
`services`	APIEntitiesCiJobRequestService	—
`steps`	APIEntitiesCiJobRequestStep	—
`suspend_options`	String	—
`token`	String	—
`variables`	String	—

APIEntitiesCiJobRequestRunnerInfo

Property	Type	Description
`runner_session_url`	String	—
`timeout`	String	—
`uuid`	String	—

APIEntitiesCiJobRequestService

Property	Type	Description
`alias`	String	—
`command`	String	—
`entrypoint`	String	—
`executor_opts`	String	—
`name`	String	—
`ports`	APIEntitiesCiJobRequestPort	—
`pull_policy`	String	—
`variables`	String	—

APIEntitiesCiJobRequestStep

Property	Type	Description
`allow_failure`	String	—
`name`	String	—
`script`	String	—
`timeout`	String	—
`when`	String	—

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`

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`

APIEntitiesProjectIdentity

Property	Type	Description
`created_at`	String (date-time)	Example: `2020-05-07T04:27:17.016Z`
`description`	String	Example: `desc`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `project1`
`name_with_namespace`	String	Example: `John Doe / project1`
`path`	String	Example: `project1`
`path_with_namespace`	String	Example: `namespace1/project1`

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	—

Request a job

Update a job

Download job artifacts

Upload job artifacts

Authorize artifacts upload

Append a patch to the job trace

List all jobs processed by a runner

Schemas

APIEntitiesCiJobBasicWithProject

APIEntitiesCiJobRequestArtifacts

APIEntitiesCiJobRequestCache

APIEntitiesCiJobRequestCredentials

APIEntitiesCiJobRequestGitInfo

APIEntitiesCiJobRequestHook

APIEntitiesCiJobRequestImage

APIEntitiesCiJobRequestJobInfo

APIEntitiesCiJobRequestPort

APIEntitiesCiJobRequestResponse

APIEntitiesCiJobRequestRunnerInfo

APIEntitiesCiJobRequestService

APIEntitiesCiJobRequestStep

APIEntitiesCiPipelineBasic

APIEntitiesCommit

APIEntitiesCustomAttribute

APIEntitiesProjectIdentity

APIEntitiesUser

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