Documentation
Documentation
https://docs.gitlab.com/api/
APIReference
https://docs.gitlab.com/api/api_resources/
Authentication
https://docs.gitlab.com/api/rest/authentication/
OpenAPI Specification
swagger: '2.0'
info:
title: GitLab access_requests jobs API
version: v4
description: Operations related to access requests
host: gitlab.com
produces:
- application/json
tags:
- name: jobs
description: Operations about jobs
paths:
/api/v4/runners/{id}/jobs:
get:
summary: List runner's jobs
description: List jobs that are being processed or were processed by the specified runner. The list of jobs is limited to projects where the user has at least the Reporter role.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID of a runner
type: integer
format: int32
required: true
- in: query
name: system_id
description: System ID associated with the runner manager
type: string
required: false
- in: query
name: status
description: Status of the job
type: string
enum:
- created
- waiting_for_resource
- preparing
- waiting_for_callback
- pending
- running
- success
- failed
- canceling
- canceled
- skipped
- manual
- scheduled
required: false
- in: query
name: order_by
description: Order by `id`
type: string
enum:
- id
required: false
- in: query
name: sort
description: Sort by `asc` or `desc` order. Specify `order_by` as well, including for `id`
type: string
default: desc
enum:
- asc
- desc
required: false
- in: query
name: cursor
description: Cursor for obtaining the next set of records
type: string
required: false
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: List jobs running on a runner
schema:
$ref: '#/definitions/API_Entities_Ci_JobBasicWithProject'
'401':
description: Unauthorized
'403':
description: No access granted
'404':
description: Runner not found
tags:
- jobs
operationId: getApiV4RunnersIdJobs
/api/v4/jobs/request:
post:
description: Request a job
produces:
- application/json
consumes:
- application/json
parameters:
- name: postApiV4JobsRequest
in: body
required: true
schema:
$ref: '#/definitions/postApiV4JobsRequest'
responses:
'201':
description: Job was scheduled
'204':
description: No job for Runner
'403':
description: Forbidden
'409':
description: Conflict
'422':
description: Runner is orphaned
'429':
description: Too Many Requests
tags:
- jobs
operationId: postApiV4JobsRequest
/api/v4/jobs/{id}:
put:
description: Update a job
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: Job's ID
type: integer
format: int32
required: true
- name: putApiV4JobsId
in: body
required: true
schema:
$ref: '#/definitions/putApiV4JobsId'
responses:
'200':
description: Job was updated
'202':
description: Update accepted
'400':
description: Unknown parameters
'403':
description: Forbidden
'409':
description: Conflict
'429':
description: Too Many Requests
tags:
- jobs
operationId: putApiV4JobsId
/api/v4/jobs/{id}/trace:
patch:
description: Append a patch to the job trace
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: Job's ID
type: integer
format: int32
required: true
- name: patchApiV4JobsIdTrace
in: body
required: true
schema:
$ref: '#/definitions/patchApiV4JobsIdTrace'
responses:
'202':
description: Trace was patched
'400':
description: Missing Content-Range header
'403':
description: Forbidden
'416':
description: Range not satisfiable
'429':
description: Too Many Requests
tags:
- jobs
operationId: patchApiV4JobsIdTrace
/api/v4/jobs/{id}/artifacts/authorize:
post:
description: Authorize uploading job artifact
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: Job's ID
type: integer
format: int32
required: true
- name: postApiV4JobsIdArtifactsAuthorize
in: body
required: true
schema:
$ref: '#/definitions/postApiV4JobsIdArtifactsAuthorize'
responses:
'200':
description: Upload allowed
'403':
description: Forbidden
'405':
description: Artifacts support not enabled
'413':
description: File too large
'429':
description: Too Many Requests
tags:
- jobs
operationId: postApiV4JobsIdArtifactsAuthorize
/api/v4/jobs/{id}/artifacts:
post:
description: Upload a job artifact
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: Job's ID
type: integer
format: int32
required: true
- name: postApiV4JobsIdArtifacts
in: body
required: true
schema:
$ref: '#/definitions/postApiV4JobsIdArtifacts'
responses:
'201':
description: Artifact uploaded
'400':
description: Bad request
'403':
description: Forbidden
'405':
description: Artifacts support not enabled
'413':
description: File too large
'429':
description: Too Many Requests
tags:
- jobs
operationId: postApiV4JobsIdArtifacts
get:
description: Download the artifacts file for job
produces:
- application/json
parameters:
- in: path
name: id
description: Job's ID
type: integer
format: int32
required: true
- in: query
name: token
description: Job's authentication token
type: string
required: false
- in: query
name: direct_download
description: Perform direct download from remote storage instead of proxying artifacts
type: boolean
default: false
required: false
responses:
'200':
description: Download allowed
'302':
description: Found
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Artifact not found
'429':
description: Too Many Requests
tags:
- jobs
operationId: getApiV4JobsIdArtifacts
definitions:
API_Entities_CustomAttribute:
type: object
properties:
key:
type: string
example: foo
value:
type: string
example: bar
required:
- key
- value
description: API_Entities_CustomAttribute model
postApiV4JobsRequest:
type: object
properties:
token:
type: string
description: Runner's authentication token
system_id:
type: string
description: Runner's system identifier
last_update:
type: string
description: Runner's queue last_update token
info:
type: object
description: Runner's metadata
properties:
name:
type: string
description: Runner's name
version:
type: string
description: Runner's version
revision:
type: string
description: Runner's revision
platform:
type: string
description: Runner's platform
architecture:
type: string
description: Runner's architecture
executor:
type: string
description: Runner's executor
features:
type: object
description: Runner's features
config:
type: object
description: Runner's config
properties:
gpus:
type: string
description: GPUs enabled
labels:
type: object
description: Runner's labels
session:
type: object
description: Runner's session data
properties:
url:
type: string
description: Session's url
certificate:
type: string
description: Session's certificate
authorization:
type: string
description: Session's authorization
required:
- token
description: Request a job
API_Entities_Ci_PipelineBasic:
type: object
properties:
id:
type: integer
format: int32
example: 1
iid:
type: integer
format: int32
example: 2
project_id:
type: integer
format: int32
example: 3
sha:
type: string
example: 0ec9e58fdfca6cdd6652c083c9edb53abc0bad52
ref:
type: string
example: feature-branch
status:
type: string
example: success
source:
type: string
example: push
created_at:
type: string
format: date-time
example: '2022-10-21T16:49:48.000+02:00'
updated_at:
type: string
format: date-time
example: '2022-10-21T16:49:48.000+02:00'
web_url:
type: string
example: https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61
required:
- id
- iid
- project_id
- sha
- ref
- status
- source
- created_at
- updated_at
- web_url
description: API_Entities_Ci_PipelineBasic model
patchApiV4JobsIdTrace:
type: object
properties:
token:
type: string
description: Job's authentication token
debug_trace:
type: boolean
description: Enable or disable the debug trace
description: Append a patch to the job trace
postApiV4JobsIdArtifacts:
type: object
properties:
file:
type: file
description: The artifact file to store (generated by Multipart middleware)
token:
type: string
description: Job's authentication token
expire_in:
type: string
description: Specify when artifact should expire
artifact_type:
type: string
description: The type of artifact
enum:
- 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
- scip
- sarif
- environment_key
default: archive
artifact_format:
type: string
description: The format of artifact
enum:
- raw
- zip
- gzip
default: zip
metadata:
type: file
description: The artifact metadata to store (generated by Multipart middleware)
accessibility:
type: string
description: Specify accessibility level of artifact private/public
required:
- file
description: Upload a job artifact
API_Entities_Commit:
type: object
properties:
id:
type: string
example: 2695effb5807a22ff3d138d593fd856244e155e7
short_id:
type: string
example: 2695effb
created_at:
type: string
format: date-time
example: '2017-07-26T11:08:53.000+02:00'
parent_ids:
type: array
items:
type: string
example:
- 2a4b78934375d7f53875269ffd4f45fd83a84ebe
title:
type: string
example: Initial commit
message:
type: string
example: Initial commit
author_name:
type: string
example: John Smith
author_email:
type: string
example: john@example.com
authored_date:
type: string
format: date-time
example: '2012-05-28T04:42:42-07:00'
committer_name:
type: string
example: Jack Smith
committer_email:
type: string
example: jack@example.com
committed_date:
type: string
format: date-time
example: '2012-05-28T04:42:42-07:00'
trailers:
type: object
example:
Merged-By: Jane Doe janedoe@gitlab.com
extended_trailers:
type: object
example:
Signed-off-by:
- John Doe <johndoe@gitlab.com>
- Jane Doe <janedoe@gitlab.com>
web_url:
type: string
example: https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746
required:
- id
- short_id
- created_at
- parent_ids
- title
- message
- author_name
- author_email
- authored_date
- committer_name
- committer_email
- committed_date
- trailers
- extended_trailers
- web_url
description: API_Entities_Commit model
API_Entities_ProjectIdentity:
type: object
properties:
id:
type: integer
format: int32
example: 1
description:
type: string
example: desc
name:
type: string
example: project1
name_with_namespace:
type: string
example: John Doe / project1
path:
type: string
example: project1
path_with_namespace:
type: string
example: namespace1/project1
created_at:
type: string
format: date-time
example: '2020-05-07T04:27:17.016Z'
required:
- id
- description
- name
- name_with_namespace
- path
- path_with_namespace
- created_at
postApiV4JobsIdArtifactsAuthorize:
type: object
properties:
token:
type: string
description: Job's authentication token
filesize:
type: integer
format: int32
description: Size of artifact file
artifact_type:
type: string
description: The type of artifact
enum:
- 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
- scip
- sarif
- environment_key
default: archive
description: Authorize uploading job artifact
putApiV4JobsId:
type: object
properties:
token:
type: string
description: Job's authentication token
state:
type: string
description: 'Job''s status: running, success, failed'
checksum:
type: string
description: Job's trace CRC32 checksum
failure_reason:
type: string
description: Job's failure_reason
output:
type: object
description: Build log state
properties:
checksum:
type: string
description: Job's trace CRC32 checksum
bytesize:
type: integer
format: int32
description: Job's trace size in bytes
exit_code:
type: integer
format: int32
description: Job's exit code
required:
- token
description: Update a job
API_Entities_User:
type: object
properties:
id:
type: integer
format: int32
example: 1
username:
type: string
example: admin
public_email:
type: string
example: john@example.com
name:
type: string
example: Administrator
state:
type: string
example: active
locked:
type: boolean
avatar_url:
type: string
example: https://gravatar.com/avatar/1
avatar_path:
type: string
example: /user/avatar/28/The-Big-Lebowski-400-400.png
custom_attributes:
type: array
items:
$ref: '#/definitions/API_Entities_CustomAttribute'
web_url:
type: string
example: https://gitlab.example.com/root
created_at:
type: string
bio:
type: string
location:
type: string
linkedin:
type: string
twitter:
type: string
discord:
type: string
website_url:
type: string
github:
type: string
job_title:
type: string
pronouns:
type: string
organization:
type: string
bot:
type: boolean
work_information:
type: string
followers:
type: string
following:
type: string
is_followed:
type: string
local_time:
type: string
required:
- id
- username
- public_email
- name
- state
- locked
- avatar_url
- web_url
- bio
- location
- linkedin
- twitter
- discord
- website_url
- github
- job_title
- pronouns
- organization
- bot
- work_information
- local_time
API_Entities_Ci_JobBasicWithProject:
type: object
properties:
id:
type: integer
format: int32
example: 1
status:
type: string
example: waiting_for_resource
stage:
type: string
example: deploy
name:
type: string
example: deploy_to_production
ref:
type: string
example: main
tag:
type: boolean
coverage:
type: number
format: float
example: 98.29
allow_failure:
type: boolean
created_at:
type: string
format: date-time
example: '2015-12-24T15:51:21.880Z'
started_at:
type: string
format: date-time
example: '2015-12-24T17:54:30.733Z'
finished_at:
type: string
format: date-time
example: '2015-12-24T17:54:31.198Z'
erased_at:
type: string
format: date-time
example: '2015-12-24T18:00:29.728Z'
duration:
type: number
format: float
example: 0.465
description: Time spent running
queued_duration:
type: number
format: float
example: 0.123
description: Time spent enqueued
user:
$ref: '#/definitions/API_Entities_User'
commit:
$ref: '#/definitions/API_Entities_Commit'
pipeline:
$ref: '#/definitions/API_Entities_Ci_PipelineBasic'
failure_reason:
type: string
example: script_failure
web_url:
type: string
example: https://example.com/foo/bar/-/jobs/1
project:
$ref: '#/definitions/API_Entities_ProjectIdentity'
required:
- id
- status
- stage
- name
- ref
- tag
- coverage
- allow_failure
- created_at
- started_at
- finished_at
- erased_at
- duration
- queued_duration
- user
- commit
- pipeline
- web_url
- project
description: API_Entities_Ci_JobBasicWithProject model
securityDefinitions:
access_token_header:
type: apiKey
name: PRIVATE-TOKEN
in: header
access_token_query:
type: apiKey
name: private_token
in: query