GitLab CI/CD Pipeline Tools

Pipeline management, job control, logs, individual artifact files, and CI/CD variable configuration.

Tools Overview

Tool	Type	Purpose
`browse_pipelines`	Query	List pipelines and jobs, read logs and artifact files
`manage_pipeline`	Command	Trigger/retry/cancel pipelines; play/retry/cancel individual jobs
`browse_variables`	Query	List and get CI/CD variables
`manage_variable`	Command	Create, update, delete variables
`browse_environments`	Query	List environments and deployments
`manage_environment`	Command	Create, update, stop, delete environments; update deployment status

browse_pipelines

View pipeline status, job details, console output, and individual artifact files.

Actions

Action	Description
`list`	List pipelines with filtering
`get`	Get single pipeline details
`jobs`	List jobs in a pipeline
`triggers`	List bridge/trigger jobs in a pipeline
`job`	Get single job details
`logs`	Read job logs with bounded memory and explicit byte truncation
`artifact_file`	Read one artifact file as bounded UTF-8 text; inspect job metadata to choose its path

Examples

List pipelinesPipeline jobsJob logs

json

{
  "action": "list",
  "project_id": "my-org/api",
  "status": "failed",
  "per_page": 10
}

json

{
  "action": "jobs",
  "project_id": "my-org/api",
  "pipeline_id": "1234",
  "job_scope": ["failed"],
  "per_page": 50
}

json

{
  "action": "logs",
  "project_id": "my-org/api",
  "job_id": "5678",
  "start": -100,
  "per_page": 100
}

Pipeline Filters

Parameter	Description
`status`	`running`, `pending`, `success`, `failed`, `canceled`, `manual`
`ref`	Branch or tag name
`source`	`push`, `web`, `schedule`, `merge_request_event`, `api`
`username`	Filter by triggering user
`order_by`	`id`, `status`, `ref`, `updated_at`

Parameter	Description
`start`	Line number (positive from start, negative from end)
`per_page`	Maximum source lines to return, default 200, maximum 10000

Without start, logs return the last per_page lines. A negative start selects from the end, limited to the last per_page lines of that selection. A nonnegative integer selects a page from the beginning. The response retains totalLines, shownLines, startLine, hasMore and nextStart; pass nextStart as the next request's start. Notice lines do not count toward these fields.

The reader streams the trace through EOF to count all source lines, retaining at most 1 MiB of source bytes for the page and the first 16 KiB per source line. Transport buffers, decoding, line metadata and response serialization need additional bounded memory. This limits retained memory, not total network traffic or scan time. Empty input counts as one line; a final newline introduces an empty last line.

If the byte budget clips content, the response adds a LOG CONTENT TRUNCATED notice and truncation metadata. Its reason is byte_limits, maxLineBytes is 16384, maxPageBytes is 1048576, and lines identifies each affected zero-based source line with omittedPrefixBytes and omittedSuffixBytes. UTF-8 fragments never introduce replacement characters solely because a limit splits a character.

For a forward page the byte budget preserves the earliest content; for a tail page it preserves the most recent retained content. Some selected lines may therefore have no remaining text. Line counts and cursors still describe the source lines, including clipped lines. Request fewer lines to reduce page clipping; line pagination cannot recover bytes omitted from an oversized individual line. Inspect the full trace in GitLab when those bytes are needed. A failed or cancelled read returns an error rather than a successful partial page.

Individual Artifact Files

Use artifact_file to read a known path uploaded through artifacts:paths on GitLab 16.0 or later, including Free instances. The action uses the selected connection, its credentials, read permissions and project restrictions. It does not download the artifacts archive or list its entries. A reports-only upload does not necessarily provide a downloadable archive entry.

json

{
  "action": "artifact_file",
  "project_id": "my-org/api",
  "job_id": "5678",
  "artifact_path": "reports/nested/test-results.json",
  "byte_offset": 0,
  "byte_limit": 65536
}

Paths are relative, with literal filenames rather than URL-encoded paths. Nested directories, spaces, ? and # in filenames are encoded safely. Absolute paths, traversal, encoded separators and control characters are refused before downloading. Discover the job through jobs and inspect job metadata or the repository CI configuration to choose the artifact path.

byte_limit defaults to 64 KiB, with a maximum of 1 MiB. The maximum byte_offset is 20 MiB. The reader validates HTTP byte ranges; when a server ignores Range, it incrementally discards the bounded prefix. It retains one window and four bytes of lookahead, then cancels the transfer. Transport queues, UTF-8 decoding and response serialization use additional bounded memory. Unexpected HTTP compression is refused before decompression.

The result contains project_id, job_id, artifact_path, text, byte_start (inclusive), byte_end (exclusive), next_byte_offset, total_bytes, complete and truncated. Continue while the returned next_byte_offset is not null. An incomplete UTF-8 character remains for the next request, preserving the source exactly; a small window may return fewer bytes than requested. total_bytes is null unless established by a validated range or actual EOF. If continuation would exceed the offset ceiling, next_byte_offset is null, complete remains false and continuation_limit reports byte_offset_limit with max_byte_offset. This is an explicit limit, not the end of the file. An empty file returns empty text with complete: true. A failed, timed-out or cancelled transfer returns an error, never apparent successful partial content.

Binary or invalid UTF-8 content returns ARTIFACT_READ_REFUSED with a reason, bounded metadata and a GitLab artifact_view_url. Other refusals describe an invalid offset, an undersized window, invalid ranges or unsupported encoding. The action does not render HTML. ANSI color escapes are preserved as text data. Treat artifact content as untrusted data. Missing paths, expired or deleted artifacts and access-hidden artifacts can all produce GitLab 404 responses; the action does not claim to distinguish them. GitLab authentication and permission failures retain their normal handling. An object-storage HTTP error is reported as storage_http_error with http_status, without asking to reauthenticate a valid GitLab account. Redirects are bounded, signed query strings are omitted from diagnostics, and credentials are never forwarded or reinjected after leaving the GitLab origin.

manage_pipeline

Trigger and control pipeline execution.

Actions

Action	Description
`create`	Trigger a new pipeline on branch/tag
`retry`	Re-run a failed/canceled pipeline
`cancel`	Stop a running pipeline
`play_job`	Trigger a manual job
`retry_job`	Re-run a failed/canceled job
`cancel_job`	Stop a running job

Examples

json

{
  "action": "create",
  "project_id": "my-org/api",
  "ref": "main",
  "variables": [{ "key": "DEPLOY_ENV", "value": "staging" }]
}

json

{
  "action": "retry",
  "project_id": "my-org/api",
  "pipeline_id": "1234"
}

json

{
  "action": "cancel",
  "project_id": "my-org/api",
  "pipeline_id": "1234"
}

json

{
  "action": "create",
  "project_id": "my-org/api",
  "ref": "main",
  "inputs": {
    "environment": "production",
    "dry_run": true,
    "replicas": 3
  }
}

json

{
  "action": "play_job",
  "project_id": "my-org/api",
  "job_id": "5678",
  "job_variables_attributes": [{ "key": "TARGET", "value": "production" }]
}

json

{
  "action": "retry_job",
  "project_id": "my-org/api",
  "job_id": "5678"
}

json

{
  "action": "cancel_job",
  "project_id": "my-org/api",
  "job_id": "5678"
}

Pipeline Inputs (GitLab 17.10+)

For pipelines with typed inputs defined in .gitlab-ci.yml:

yaml

# .gitlab-ci.yml
spec:
  inputs:
    environment:
      type: string
      options: [staging, production]
    dry_run:
      type: boolean
      default: false
    replicas:
      type: number
      default: 1

Trigger with inputs:

json

{
  "action": "create",
  "project_id": "my-org/api",
  "ref": "main",
  "inputs": {
    "environment": "production",
    "dry_run": true,
    "replicas": 3
  }
}

Variables vs Inputs

variables: Legacy key-value pairs, no type validation
inputs: Typed parameters with schema validation (requires GitLab 17.10+ for the pipeline creation API)

You can use both in the same request if needed.

browse_variables / manage_variable

Manage CI/CD environment variables with scoping and protection.

Examples

List variablesCreate variableUpdate variableDelete variable

json

{
  "action": "list",
  "namespace": "my-org/api",
  "per_page": 50
}

json

{
  "action": "create",
  "namespace": "my-org/api",
  "key": "DEPLOY_TOKEN",
  "value": "secure-value",
  "protected": true,
  "masked": true,
  "environment_scope": "production"
}

json

{
  "action": "update",
  "namespace": "my-org/api",
  "key": "DEPLOY_TOKEN",
  "value": "new-value",
  "protected": true,
  "masked": true
}

json

{
  "action": "delete",
  "namespace": "my-org/api",
  "key": "OLD_VARIABLE"
}

Variable Properties

Property	Description
`protected`	Only available to protected branches/tags
`masked`	Hidden in job logs (requires 8+ chars, specific charset)
`environment_scope`	`*` for all, or specific like `production`
`variable_type`	`env_var` (default) or `file`

browse_environments

Inspect environments and their deployment history. Gated by USE_ENVIRONMENTS.

Actions

Action	Description
`list`	List environments for a project
`get`	Get a single environment by ID, including its last deployment
`list_deployments`	List deployments for a project, optionally filtered by environment

Examples

List environmentsGet environmentList deployments

json

{
  "action": "list",
  "project_id": "my-org/api",
  "states": "available"
}

json

{
  "action": "get",
  "project_id": "my-org/api",
  "environment_id": 42
}

json

{
  "action": "list_deployments",
  "project_id": "my-org/api",
  "environment": "production",
  "status": "success"
}

manage_environment

Create and control environments, and update deployment status. Deployments are folded into this tool rather than a separate pair. Gated by USE_ENVIRONMENTS.

Actions

Action	Description
`create`	Create a new environment
`update`	Update an existing environment (name cannot be changed via the API)
`stop`	Stop an environment (required before it can be deleted)
`delete`	Delete a stopped environment
`update_deployment_status`	Update the status of a deployment. Only deployments not tied to a pipeline job can be updated.

Examples

Create environmentStop environmentUpdate deployment status

json

{
  "action": "create",
  "project_id": "my-org/api",
  "name": "staging",
  "external_url": "https://staging.example.com",
  "tier": "staging"
}

json

{
  "action": "stop",
  "project_id": "my-org/api",
  "environment_id": 42
}

json

{
  "action": "update_deployment_status",
  "project_id": "my-org/api",
  "deployment_id": 1001,
  "status": "success"
}

GitLab CI/CD Pipeline Tools ​

Tools Overview ​

browse_pipelines ​

Actions ​

Examples ​

Pipeline Filters ​

Log Navigation ​

Individual Artifact Files ​

manage_pipeline ​

Actions ​

Examples ​

Pipeline Inputs (GitLab 17.10+) ​

browse_variables / manage_variable ​

Examples ​

Variable Properties ​

browse_environments ​

Actions ​

Examples ​

manage_environment ​

Actions ​

Examples ​

Related Guides ​

GitLab CI/CD Pipeline Tools

Tools Overview

browse_pipelines

Actions

Examples

Pipeline Filters

Log Navigation

Individual Artifact Files

manage_pipeline

Actions

Examples

Pipeline Inputs (GitLab 17.10+)

browse_variables / manage_variable

Examples

Variable Properties

browse_environments

Actions

Examples

manage_environment

Actions

Examples

Related Guides