automateyournetwork/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

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

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

Retry a Failed Pipeline

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

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

Cancel a Running Pipeline

1. Verify the pipeline is currently running
2. Confirm with operator
3. 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

1. Verify the target project exists via get_project
2. Present the issue details to the operator for confirmation
3. 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

1. Read current issue state via get_issue
2. Present proposed changes to operator
3. 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

1. Verify source and target branches exist via compare_branches
2. Present MR details to operator for confirmation
3. 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

1. Read current MR state via get_merge_request
2. Present proposed changes to operator
3. 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

1. Verify MR has no conflicts and approvals are met via get_merge_request
2. Explicitly confirm with operator — this is irreversible
3. 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:

1. Before: Tool name, parameters (excluding tokens), and operator intent
2. 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")