gitlab-devops

GitLab DevOps Skill

Golden Rule

Never execute write operations (create, update, delete, merge) without explicit operator confirmation. All mutating actions — creating issues, merging MRs, triggering pipelines, deleting labels — require human-in-the-loop approval before invocation (Constitution XIV). Always observe current state before making changes (Constitution II: Read-Before-Write).

MCP Server

This skill uses tools provided by the gitlab-mcp server (@zereight/mcp-gitlab), a community MCP server with 98+ tools for GitLab operations. The server is spawned locally via npx -y @zereight/mcp-gitlab and communicates over stdio transport.

Environment Variables

Variable	Required	Description
`GITLAB_PERSONAL_ACCESS_TOKEN`	Yes	GitLab PAT with `api` or `read_api` scope
`GITLAB_API_URL`	No	GitLab API URL (default: `https://gitlab.com`)
`GITLAB_READ_ONLY_MODE`	No	Restrict to read-only tools (default: `false`)

Workflow 1: Query Issues and Merge Requests (P1 — MVP)

Use this workflow to search, list, and inspect GitLab issues and merge requests for network project tracking.

Step 1: Discover Projects

Find the target project by name or keyword:

Tool: search_projects
Parameters: { "query": "network-automation" }

Or list all accessible projects:

Tool: list_projects
Parameters: { "per_page": 20 }

Step 2: List Issues

Query issues with filters for state, labels, assignee, or milestone:

Tool: list_issues
Parameters: {
  "project_id": "network-team/network-automation",
  "state": "opened",
  "labels": "outage",
  "assignee_username": "jcapobianco"
}

Step 3: Get Issue Details

Retrieve full details for a specific issue:

Tool: get_issue
Parameters: {
  "project_id": "network-team/network-automation",
  "issue_iid": 42
}

Step 4: View Issue Comments

List the discussion thread on an issue:

Tool: list_issue_comments
Parameters: {
  "project_id": "network-team/network-automation",
  "issue_iid": 42
}

Step 5: List Merge Requests

Query merge requests with filters:

Tool: list_merge_requests
Parameters: {
  "project_id": "network-team/infra-configs",
  "state": "opened",
  "labels": "needs-review"
}

Step 6: Get Merge Request Details

Retrieve MR details including diff stats and approval status:

Tool: get_merge_request
Parameters: {
  "project_id": "network-team/infra-configs",
  "merge_request_iid": 15
}

Example Prompts

"Show me open issues in project network-automation"
"List merge requests awaiting review in project infra-configs"
"Get details for issue #42 in network-automation"
"Show my assigned issues across all projects"
"Find all projects matching 'network'"

Workflow 2: Monitor CI/CD Pipelines (P2)

Use this workflow to monitor pipeline status, inspect job details, and troubleshoot failures.

Step 1: List Pipelines

View pipeline executions for a project:

Tool: list_pipelines
Parameters: {
  "project_id": "network-team/network-configs",
  "status": "failed",
  "ref": "main"
}

Step 2: Get Pipeline Details

Retrieve details for a specific pipeline:

Tool: get_pipeline
Parameters: {
  "project_id": "network-team/network-configs",
  "pipeline_id": 123
}

Step 3: List Pipeline Jobs

Inspect jobs within a pipeline:

Tool: get_pipeline_jobs
Parameters: {
  "project_id": "network-team/network-configs",
  "pipeline_id": 123
}

Step 4: Get Job Log

Retrieve console output for troubleshooting:

Tool: get_pipeline_job_log
Parameters: {
  "project_id": "network-team/network-configs",
  "job_id": 456
}

Pipeline Control (Write Operations)

Requires operator confirmation. Skipped in read-only mode.

Trigger a New Pipeline

Verify the target branch exists and check current pipeline state
Present the action to the operator for confirmation
Trigger the pipeline:

Tool: create_pipeline
Parameters: {
  "project_id": "network-team/network-configs",
  "ref": "feature/bgp-tuning"
}

Retry a Failed Pipeline

Check the pipeline status to confirm it is in a failed state
Confirm with operator
Retry:

Tool: retry_pipeline
Parameters: {
  "project_id": "network-team/network-configs",
  "pipeline_id": 123
}

Cancel a Running Pipeline

Verify the pipeline is currently running
Confirm with operator
Cancel:

Tool: cancel_pipeline
Parameters: {
  "project_id": "network-team/network-configs",
  "pipeline_id": 124
}

Example Prompts

"Show pipelines for project network-configs"
"Show failed pipelines on the main branch"
"Get the job log for pipeline #123"
"Retry the failed pipeline for network-configs"
"Cancel the running pipeline #124"

Workflow 3: Browse Repositories and Files (P3)

Use this workflow to inspect repository structure, read file contents, and review change history.

Step 1: List Repository Tree

View the directory structure:

Tool: list_repository_tree
Parameters: {
  "project_id": "network-team/network-configs",
  "path": "ansible/",
  "ref": "main"
}

Step 2: Get File Content

Read a specific file:

Tool: get_file_content
Parameters: {
  "project_id": "network-team/network-configs",
  "file_path": "ansible/site.yml",
  "ref": "main"
}

Step 3: List Commits

View commit history with filters:

Tool: list_commits
Parameters: {
  "project_id": "network-team/network-configs",
  "ref_name": "main",
  "path": "ansible/",
  "since": "2026-03-01T00:00:00Z"
}

Step 4: Get Commit Details

Inspect a specific commit with diff:

Tool: get_commit
Parameters: {
  "project_id": "network-team/network-configs",
  "sha": "abc123def"
}

Step 5: Compare Branches

Review differences between branches:

Tool: compare_branches
Parameters: {
  "project_id": "network-team/network-configs",
  "from": "main",
  "to": "feature/bgp-tuning"
}

Example Prompts

"Show the directory structure of project network-configs"
"Show me the contents of ansible/site.yml on the develop branch"
"List recent commits on the main branch for the ansible/ directory"
"Compare the main and feature/bgp-tuning branches"
"Show the diff for commit abc123def"

Workflow 4: Manage Issues and Merge Requests (P4)

All write operations require operator confirmation. Skipped in read-only mode.

Issue Management

Create an Issue

Verify the target project exists via get_project
Present the issue details to the operator for confirmation
Create the issue:

Tool: create_issue
Parameters: {
  "project_id": "network-team/network-automation",
  "title": "BGP peer flapping on router-01",
  "description": "Router-01 BGP peer to router-02 (192.168.1.1) is flapping every 30 seconds. Hold timer expiry detected. Investigate and resolve.",
  "labels": "outage,bgp,priority::critical",
  "assignee_ids": [42]
}

Update an Issue

Read current issue state via get_issue
Present proposed changes to operator
Update:

Tool: update_issue
Parameters: {
  "project_id": "network-team/network-automation",
  "issue_iid": 42,
  "state_event": "close",
  "labels": "outage,bgp,resolved"
}

Add a Comment

Tool: add_issue_comment
Parameters: {
  "project_id": "network-team/network-automation",
  "issue_iid": 42,
  "body": "Root cause identified: BGP hold timer set to 10s, peer timer at 30s. Aligned timers to 90/30. Peering stable for 15 minutes."
}

Merge Request Management

Create a Merge Request

Verify source and target branches exist via compare_branches
Present MR details to operator for confirmation
Create the MR:

Tool: create_merge_request
Parameters: {
  "project_id": "network-team/infra-configs",
  "title": "fix: align BGP hold timers on router-01",
  "source_branch": "fix/bgp-timer-alignment",
  "target_branch": "main",
  "description": "Aligns BGP hold timer from 10s to 90s on router-01 peer to router-02.\n\nServiceNow CR: CHG0012345\nGAIT Session: gait-abc123"
}

Update a Merge Request

Read current MR state via get_merge_request
Present proposed changes to operator
Update:

Tool: update_merge_request
Parameters: {
  "project_id": "network-team/infra-configs",
  "merge_request_iid": 15,
  "labels": "approved,ready-to-merge"
}

Add a Comment to a Merge Request

Tool: add_merge_request_comment
Parameters: {
  "project_id": "network-team/infra-configs",
  "merge_request_iid": 15,
  "body": "Verified in CML lab. BGP peering stable after timer change. Ready to merge."
}

Merge a Merge Request

Verify MR has no conflicts and approvals are met via get_merge_request
Explicitly confirm with operator — this is irreversible
Merge:

Tool: merge_merge_request
Parameters: {
  "project_id": "network-team/infra-configs",
  "merge_request_iid": 15,
  "squash": true,
  "should_remove_source_branch": true
}

Example Prompts

"Create an issue in project network-automation titled 'BGP peer flapping on router-01'"
"Close issue #42 in network-automation"
"Create a merge request from fix/bgp-timer-alignment to main in infra-configs"
"Merge MR #15 in infra-configs with squash"
"Add a comment to MR #15: 'Verified in lab, ready to merge'"

Workflow 5: Manage Labels, Milestones, Releases, and Wiki (P5)

Label Management

Tool: list_labels
Parameters: { "project_id": "network-team/network-automation" }

Tool: create_label  (requires confirmation, skipped in read-only mode)
Parameters: {
  "project_id": "network-team/network-automation",
  "name": "critical-infrastructure",
  "color": "#FF0000"
}

Milestone Management

Tool: list_milestones
Parameters: { "project_id": "network-team/network-automation" }

Tool: create_milestone  (requires confirmation, skipped in read-only mode)
Parameters: {
  "project_id": "network-team/network-automation",
  "title": "Q2 2026 Network Refresh",
  "due_date": "2026-06-30"
}

Release Management

Tool: list_releases
Parameters: { "project_id": "network-team/network-configs" }

Tool: get_release
Parameters: {
  "project_id": "network-team/network-configs",
  "tag_name": "v2.1.0"
}

Tool: create_release  (requires confirmation, skipped in read-only mode)
Parameters: {
  "project_id": "network-team/network-configs",
  "tag_name": "v2.2.0",
  "name": "Network Configs v2.2.0",
  "description": "BGP timer alignment and OSPF area optimization"
}

Wiki Page Management

Tool: list_wiki_pages
Parameters: { "project_id": "network-team/network-automation" }

Tool: get_wiki_page
Parameters: {
  "project_id": "network-team/network-automation",
  "slug": "bgp-runbook"
}

Tool: create_wiki_page  (requires confirmation, skipped in read-only mode)
Parameters: {
  "project_id": "network-team/network-automation",
  "title": "Incident Postmortem: Router-01 BGP Flap",
  "content": "## Summary\n\nBGP peering between router-01 and router-02 was flapping..."
}

Example Prompts

"List milestones for project network-automation"
"Create a label called 'critical-infrastructure' with red color"
"Show releases for project network-configs"
"Show the BGP runbook wiki page in network-automation"
"Create a wiki page for the router-01 incident postmortem"

GAIT Audit Logging

All GitLab interactions MUST be logged to the GAIT audit trail via gait_mcp tools at skill invocation level.

Logging Pattern

For each operation, log:

Before: Tool name, parameters (excluding tokens), and operator intent
After: Result summary (issue key created, pipeline status, etc.)

Tool: gait_log
Parameters: {
  "action": "gitlab.list_issues",
  "details": "Queried open issues in network-automation with label 'outage'",
  "result": "Returned 7 open issues"
}

For write operations, include the confirmation step:

Tool: gait_log
Parameters: {
  "action": "gitlab.create_issue",
  "details": "Created issue 'BGP peer flapping on router-01' in network-automation. Operator confirmed.",
  "result": "Issue #43 created at https://gitlab.com/network-team/network-automation/-/issues/43"
}

Read-Only Mode

When GITLAB_READ_ONLY_MODE=true, the skill restricts to observation-only operations:

Allowed tools (read-only):

list_issues, get_issue, list_issue_comments
list_merge_requests, get_merge_request
list_pipelines, get_pipeline, get_pipeline_jobs, get_pipeline_job_log
list_repository_tree, get_file_content, list_commits, get_commit, compare_branches
list_projects, get_project, search_projects
list_labels, list_milestones, list_releases, get_release
list_wiki_pages, get_wiki_page

Blocked tools (write operations — skipped with message):

create_issue, update_issue, add_issue_comment
create_merge_request, update_merge_request, merge_merge_request, add_merge_request_comment
create_pipeline, retry_pipeline, cancel_pipeline
create_label, update_label, delete_label
create_milestone, update_milestone
create_release
create_wiki_page, update_wiki_page, delete_wiki_page

When a write tool is requested in read-only mode, respond: "GitLab read-only mode is enabled (GITLAB_READ_ONLY_MODE=true). Write operations are disabled. Contact your administrator to enable write access."

Integration with Other Skills

servicenow-change-workflow — Reference ServiceNow CR numbers in MR descriptions and issue comments for ITSM traceability
gait-session-tracking — All GitLab operations are logged to the GAIT audit trail
github-ops — Similar workflows for GitHub-hosted repositories; use gitlab-devops for GitLab and github-ops for GitHub
canvas-network-viz — Visualize pipeline status and project metrics in the Canvas/A2UI dashboard

Important Rules

Never expose personal access tokens in logs, comments, or error messages
Always verify project existence before write operations
Reference ServiceNow CR numbers in MR descriptions when applicable
Log all operations to GAIT for audit compliance
In read-only mode, gracefully skip write operations with a clear message
For self-hosted GitLab with nested groups, use full path (e.g., "org/team/sub-team/project")

About this skill

Golden Rule

MCP Server

Environment Variables

Workflow 1: Query Issues and Merge Requests (P1 — MVP)

Step 1: Discover Projects

Step 2: List Issues

Step 3: Get Issue Details

Step 4: View Issue Comments

Step 5: List Merge Requests

Step 6: Get Merge Request Details

Example Prompts

Workflow 2: Monitor CI/CD Pipelines (P2)

Step 1: List Pipelines

Step 2: Get Pipeline Details

Step 3: List Pipeline Jobs

Step 4: Get Job Log

Pipeline Control (Write Operations)

Trigger a New Pipeline

Retry a Failed Pipeline

Cancel a Running Pipeline

Example Prompts

Workflow 3: Browse Repositories and Files (P3)

Step 1: List Repository Tree

Step 2: Get File Content

Step 3: List Commits

Step 4: Get Commit Details

Step 5: Compare Branches

Example Prompts

Workflow 4: Manage Issues and Merge Requests (P4)

Issue Management

Create an Issue

Update an Issue

Add a Comment

Merge Request Management

Create a Merge Request

Update a Merge Request

Add a Comment to a Merge Request

Merge a Merge Request

Example Prompts

Workflow 5: Manage Labels, Milestones, Releases, and Wiki (P5)

Label Management

Milestone Management

Release Management

Wiki Page Management

Example Prompts

GAIT Audit Logging

Logging Pattern

Read-Only Mode

Integration with Other Skills

Important Rules