GitLab API — jobs

naftiko: 1.0.0-alpha2
info:
  label: GitLab API — jobs
  description: 'GitLab API — jobs. 7 operations. Lead operation: List runner''s jobs. Self-contained Naftiko capability covering
    one Gitlab Ci business surface.'
  tags:
  - Gitlab Ci
  - jobs
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    GITLAB_CI_API_KEY: GITLAB_CI_API_KEY
capability:
  consumes:
  - type: http
    namespace: gitlab-ci-jobs
    baseUri: https://gitlab.com
    description: GitLab API — jobs business capability. Self-contained, no shared references.
    resources:
    - name: api-v4-jobs-request
      path: /api/v4/jobs/request
      operations:
      - name: postapiv4jobsrequest
        method: POST
        description: Request a job
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: postApiV4JobsRequest
          in: body
          type: string
          required: true
    - name: api-v4-jobs-id
      path: /api/v4/jobs/{id}
      operations:
      - name: putapiv4jobsid
        method: PUT
        description: Update a job
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Job's ID
          required: true
        - name: putApiV4JobsId
          in: body
          type: string
          required: true
    - name: api-v4-jobs-id-artifacts
      path: /api/v4/jobs/{id}/artifacts
      operations:
      - name: postapiv4jobsidartifacts
        method: POST
        description: Upload a job artifact
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Job's ID
          required: true
        - name: postApiV4JobsIdArtifacts
          in: body
          type: string
          required: true
      - name: getapiv4jobsidartifacts
        method: GET
        description: Download the artifacts file for job
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Job's ID
          required: true
        - name: token
          in: query
          type: string
          description: Job's authentication token
        - name: direct_download
          in: query
          type: boolean
          description: Perform direct download from remote storage instead of proxying artifacts
    - name: api-v4-jobs-id-artifacts-authorize
      path: /api/v4/jobs/{id}/artifacts/authorize
      operations:
      - name: postapiv4jobsidartifactsauthorize
        method: POST
        description: Authorize uploading job artifact
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Job's ID
          required: true
        - name: postApiV4JobsIdArtifactsAuthorize
          in: body
          type: string
          required: true
    - name: api-v4-jobs-id-trace
      path: /api/v4/jobs/{id}/trace
      operations:
      - name: patchapiv4jobsidtrace
        method: PATCH
        description: Append a patch to the job trace
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: Job's ID
          required: true
        - name: patchApiV4JobsIdTrace
          in: body
          type: string
          required: true
    - name: api-v4-runners-id-jobs
      path: /api/v4/runners/{id}/jobs
      operations:
      - name: getapiv4runnersidjobs
        method: GET
        description: List runner's jobs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The ID of a runner
          required: true
        - name: system_id
          in: query
          type: string
          description: System ID associated with the runner manager
        - name: status
          in: query
          type: string
          description: Status of the job
        - name: order_by
          in: query
          type: string
          description: Order by `id`
        - name: sort
          in: query
          type: string
          description: Sort by `asc` or `desc` order. Specify `order_by` as well, including for `id`
        - name: cursor
          in: query
          type: string
          description: Cursor for obtaining the next set of records
        - name: page
          in: query
          type: integer
          description: Current page number
        - name: per_page
          in: query
          type: integer
          description: Number of items per page
  exposes:
  - type: rest
    namespace: gitlab-ci-jobs-rest
    port: 8080
    description: REST adapter for GitLab API — jobs. One Spectral-compliant resource per consumed operation, prefixed with
      /v1.
    resources:
    - path: /v1/api/v4/jobs/request
      name: api-v4-jobs-request
      description: REST surface for api-v4-jobs-request.
      operations:
      - method: POST
        name: postapiv4jobsrequest
        description: Request a job
        call: gitlab-ci-jobs.postapiv4jobsrequest
        with:
          postApiV4JobsRequest: rest.postApiV4JobsRequest
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/jobs/{id}
      name: api-v4-jobs-id
      description: REST surface for api-v4-jobs-id.
      operations:
      - method: PUT
        name: putapiv4jobsid
        description: Update a job
        call: gitlab-ci-jobs.putapiv4jobsid
        with:
          id: rest.id
          putApiV4JobsId: rest.putApiV4JobsId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/jobs/{id}/artifacts
      name: api-v4-jobs-id-artifacts
      description: REST surface for api-v4-jobs-id-artifacts.
      operations:
      - method: POST
        name: postapiv4jobsidartifacts
        description: Upload a job artifact
        call: gitlab-ci-jobs.postapiv4jobsidartifacts
        with:
          id: rest.id
          postApiV4JobsIdArtifacts: rest.postApiV4JobsIdArtifacts
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: getapiv4jobsidartifacts
        description: Download the artifacts file for job
        call: gitlab-ci-jobs.getapiv4jobsidartifacts
        with:
          id: rest.id
          token: rest.token
          direct_download: rest.direct_download
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/jobs/{id}/artifacts/authorize
      name: api-v4-jobs-id-artifacts-authorize
      description: REST surface for api-v4-jobs-id-artifacts-authorize.
      operations:
      - method: POST
        name: postapiv4jobsidartifactsauthorize
        description: Authorize uploading job artifact
        call: gitlab-ci-jobs.postapiv4jobsidartifactsauthorize
        with:
          id: rest.id
          postApiV4JobsIdArtifactsAuthorize: rest.postApiV4JobsIdArtifactsAuthorize
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/jobs/{id}/trace
      name: api-v4-jobs-id-trace
      description: REST surface for api-v4-jobs-id-trace.
      operations:
      - method: PATCH
        name: patchapiv4jobsidtrace
        description: Append a patch to the job trace
        call: gitlab-ci-jobs.patchapiv4jobsidtrace
        with:
          id: rest.id
          patchApiV4JobsIdTrace: rest.patchApiV4JobsIdTrace
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/v4/runners/{id}/jobs
      name: api-v4-runners-id-jobs
      description: REST surface for api-v4-runners-id-jobs.
      operations:
      - method: GET
        name: getapiv4runnersidjobs
        description: List runner's jobs
        call: gitlab-ci-jobs.getapiv4runnersidjobs
        with:
          id: rest.id
          system_id: rest.system_id
          status: rest.status
          order_by: rest.order_by
          sort: rest.sort
          cursor: rest.cursor
          page: rest.page
          per_page: rest.per_page
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: gitlab-ci-jobs-mcp
    port: 9090
    transport: http
    description: MCP adapter for GitLab API — jobs. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: request-job
      description: Request a job
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-jobs.postapiv4jobsrequest
      with:
        postApiV4JobsRequest: tools.postApiV4JobsRequest
      outputParameters:
      - type: object
        mapping: $.
    - name: update-job
      description: Update a job
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: gitlab-ci-jobs.putapiv4jobsid
      with:
        id: tools.id
        putApiV4JobsId: tools.putApiV4JobsId
      outputParameters:
      - type: object
        mapping: $.
    - name: upload-job-artifact
      description: Upload a job artifact
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-jobs.postapiv4jobsidartifacts
      with:
        id: tools.id
        postApiV4JobsIdArtifacts: tools.postApiV4JobsIdArtifacts
      outputParameters:
      - type: object
        mapping: $.
    - name: download-artifacts-file-job
      description: Download the artifacts file for job
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-jobs.getapiv4jobsidartifacts
      with:
        id: tools.id
        token: tools.token
        direct_download: tools.direct_download
      outputParameters:
      - type: object
        mapping: $.
    - name: authorize-uploading-job-artifact
      description: Authorize uploading job artifact
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: gitlab-ci-jobs.postapiv4jobsidartifactsauthorize
      with:
        id: tools.id
        postApiV4JobsIdArtifactsAuthorize: tools.postApiV4JobsIdArtifactsAuthorize
      outputParameters:
      - type: object
        mapping: $.
    - name: append-patch-job-trace
      description: Append a patch to the job trace
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: gitlab-ci-jobs.patchapiv4jobsidtrace
      with:
        id: tools.id
        patchApiV4JobsIdTrace: tools.patchApiV4JobsIdTrace
      outputParameters:
      - type: object
        mapping: $.
    - name: list-runner-s-jobs
      description: List runner's jobs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: gitlab-ci-jobs.getapiv4runnersidjobs
      with:
        id: tools.id
        system_id: tools.system_id
        status: tools.status
        order_by: tools.order_by
        sort: tools.sort
        cursor: tools.cursor
        page: tools.page
        per_page: tools.per_page
      outputParameters:
      - type: object
        mapping: $.