CI/CD Workflow Examples
These step-by-step CI/CD workflows show how to diagnose pipeline failures, manage CI/CD variables, schedule builds, control environments, validate config, and read DORA metrics — all in natural language. Each example pairs the prompt you type with the exact catalog action the server runs, written as domain.action → parameters: on the default dynamic surface that is the action you pass to gitlab_execute_action, and with GITLAB_MCP_TOOL_SURFACE=meta it is the action of the gitlab_<domain> meta-tool, so you can see precisely what happens behind the scenes and reuse the call directly.
Diagnose a failing pipeline
Section titled “Diagnose a failing pipeline”When a pipeline fails, this workflow takes you from the list of failed pipelines down to the specific job log that explains the failure — without leaving your assistant. List failed pipelines, drill into the failing jobs, then read the job log to find the root cause.
Get pipeline overview
Section titled “Get pipeline overview”Prompt: “Show me all failed pipelines in my-group/backend”
pipeline.list → project_id: "my-group/backend", status: "failed"Returns: pipeline IDs, branches, failure reasons, and durations.
Drill into a failed pipeline
Section titled “Drill into a failed pipeline”Prompt: “Show me the failed jobs in pipeline #45892”
job.list → project_id: "my-group/backend", pipeline_id: 45892, scope: ["failed"]Returns: job names, stages, failure messages, and runner info.
Read job logs
Section titled “Read job logs”Prompt: “Get the log output from the ‘test-integration’ job in pipeline #45892”
job.trace → project_id: "my-group/backend", job_id: 98765Returns: full job log output. Useful for diagnosing test failures without opening the GitLab UI.
Manage CI/CD variables
Section titled “Manage CI/CD variables”Configure the environment your pipelines run in by listing, creating, and scoping CI/CD variables. Use this to inspect what is already set, add secrets like deploy tokens with masking and protection, or restrict a variable to a single environment.
List project variables
Section titled “List project variables”Prompt: “What CI/CD variables are configured in the backend project?”
ci_variable.list → project_id: "my-group/backend"Returns: variable keys, values, protection status, masking status, and environment scopes. The value comes back as GitLab returns it to the token, so treat the output as sensitive.
Add a deployment variable
Section titled “Add a deployment variable”Prompt: “Add a CI/CD variable DEPLOY_TOKEN with value ‘abc123’ to the backend project, masked and protected”
ci_variable.create → project_id: "my-group/backend", key: "DEPLOY_TOKEN", value: "abc123", masked: true, protected: trueUpdate variable scope
Section titled “Update variable scope”Prompt: “Update the DATABASE_URL variable in backend to only apply to the production environment”
ci_variable.update → project_id: "my-group/backend", key: "DATABASE_URL", environment_scope: "production"Pipeline schedules
Section titled “Pipeline schedules”Automate recurring pipelines with cron-based schedules — for example a nightly build — and review which schedules already exist and when they run next.
Create a nightly build
Section titled “Create a nightly build”Prompt: “Create a pipeline schedule that runs every night at 2 AM UTC on the main branch”
pipeline.schedule_create → project_id: "my-group/backend", description: "Nightly build", ref: "main", cron: "0 2 * * *", cron_timezone: "UTC"List active schedules
Section titled “List active schedules”Prompt: “Show me all pipeline schedules in the backend project”
pipeline.schedule_list → project_id: "my-group/backend"Returns: schedule descriptions, cron expressions, next run times, and owner info.
Environment management
Section titled “Environment management”Track and control where your code is deployed. List environments to see their state and URLs, review deployment history for production, and stop ephemeral review environments when they are no longer needed.
List environments
Section titled “List environments”Prompt: “Show me all environments for the backend project”
environment.list → project_id: "my-group/backend"Returns: environment names, external URLs, last deployment info, and state.
Check deployment history
Section titled “Check deployment history”Prompt: “Show recent deployments to the production environment”
environment.deployment_list → project_id: "my-group/backend", environment: "production"Stop a review environment
Section titled “Stop a review environment”Prompt: “Stop the review/feature-login environment in the backend project”
environment.stop → project_id: "my-group/backend", environment_id: 42Validate CI configuration
Section titled “Validate CI configuration”Catch .gitlab-ci.yml mistakes before they break a pipeline by linting the config. The server returns the validation status alongside the fully merged YAML, so you can confirm that includes and templates resolve as expected.
Lint CI config
Section titled “Lint CI config”Prompt: “Validate the .gitlab-ci.yml in my-group/backend for syntax errors”
template.lint_project → project_id: "my-group/backend"Returns: validation status, merged YAML, warnings, and error details.
DORA metrics
Section titled “DORA metrics”Measure delivery performance with the four DORA metrics — deployment frequency, lead time for changes, time to restore service, and change failure rate — at either project or group scope. DORA metrics require a GitLab Premium or Ultimate license.
Project performance
Section titled “Project performance”Prompt: “Show me the deployment frequency for the backend project over January”
dora_metrics.project → project_id: "my-group/backend", metric: "deployment_frequency", start_date: "2024-01-01", end_date: "2024-01-31"Returns: one series of daily values for the requested metric. metric is required and takes one of deployment_frequency, lead_time_for_changes, time_to_restore_service or change_failure_rate, so the four metrics are four calls.
Group-level metrics
Section titled “Group-level metrics”Prompt: “Compare the monthly change failure rate across all projects in the platform group”
dora_metrics.group → group_id: "platform", metric: "change_failure_rate", interval: "monthly"Returns: the metric aggregated for the entire group per interval, useful for engineering leadership dashboards.
Dynamic-first CI/CD calls
Section titled “Dynamic-first CI/CD calls”In the default dynamic surface, the assistant discovers the exact CI/CD action and its schema first, then executes it, so the domain.action IDs above are exactly what it passes to gitlab_execute_action. The two-step pattern is find, then execute:
gitlab_find_action → query: "latest pipeline status for project"gitlab_execute_action → action: "pipeline.latest", params: { project_id: "42" }For failed jobs, discover the log or retry action first, then execute with the returned schema:
gitlab_find_action → query: "get failed job trace"gitlab_execute_action → action: "job.trace", params: { project_id: "42", job_id: 9876 }Frequently asked questions
How do I debug a failing GitLab pipeline with an AI assistant?
Work down from the pipeline to the job log. Run pipeline.list with status: failed to find the run, job.list with the pipeline ID to see which job failed, then job.trace to fetch that job's log so the assistant can read the actual error. On the default dynamic surface these are gitlab_execute_action actions; with GITLAB_MCP_TOOL_SURFACE=meta they are the list action of gitlab_pipeline and the list and trace actions of gitlab_job. Reading the log is the step that matters — pipeline status alone rarely explains a failure.
Can an AI assistant retry or cancel a GitLab pipeline?
Yes. pipeline.retry and pipeline.cancel act on a pipeline, and job.retry and job.cancel on a single job (the retry and cancel actions of the gitlab_pipeline and gitlab_job meta-tools when GITLAB_MCP_TOOL_SURFACE=meta). Retrying a pipeline reruns only its failed jobs, while retrying one job reruns just that job. Both are mutating actions, so they are unavailable under GITLAB_MCP_READ_ONLY=true and return a preview under GITLAB_MCP_SAFE_MODE=true.
How do I check my CI configuration before pushing?
Use the template.lint action (gitlab_execute_action on the default surface; gitlab_template with action: lint when GITLAB_MCP_TOOL_SURFACE=meta; the gitlab_ci_lint tool on the individual surface) to validate .gitlab-ci.yml against GitLab's own linter without committing anything. It reports syntax errors and the merged configuration after include: resolution, which is the fastest way to catch a broken extends: or a typo in a job name. Because it only validates, it is available in read-only deployments.
Are CI/CD variable values visible to the AI assistant?
Listing variables with ci_variable.list (gitlab_ci_variable with action: list on the meta surface) returns values for variables the token is allowed to read, so treat that output as sensitive — masked and protected variables are governed by GitLab's own rules, not by the MCP server. If an assistant should never see them, use a token without the required scope, or run with GITLAB_MCP_READ_ONLY=true so no variable can be created or changed.