automateyournetwork/jenkins-cicd

Jenkins CI/CD Skill

Purpose

Manage Jenkins CI/CD pipelines for network automation workflows. This skill provides operational workflows for monitoring job and build status, triggering builds with parameters, analyzing build logs for troubleshooting, and tracking SCM changes across Jenkins projects.

The Jenkins MCP server is an official Jenkins plugin running natively inside Jenkins via Streamable HTTP transport — netclaw connects to it as a remote HTTP client.

Golden Rule

Never trigger a build or modify build metadata without explicit operator confirmation. All write operations (triggerBuild, updateBuild) require human-in-the-loop approval per Constitution XIV. Always read current state before proposing any write action (Constitution II — Read-Before-Write).

---

Workflow 1: Pipeline and Build Monitoring (US1 — MVP)

Monitor Jenkins job status, build results, queue state, and pipeline run history.

Steps

1. List all jobs — Use getJobs with optional pagination (offset, limit) and regex name filter to discover available jobs.

   Tool: getJobs
   Parameters: { "nameFilter": "deploy-.*", "offset": 0, "limit": 25 }
   

2. Get job details — Use getJob with the full job name (supports folder paths like folder1/folder2/job-name) to retrieve job configuration, last build number, and health status.

   Tool: getJob
   Parameters: { "fullName": "network-automation/deploy-network-config" }
   

3. Get build details — Use getBuild with job name and build number to retrieve result, duration, timestamp, parameters, and causes.

   Tool: getBuild
   Parameters: { "jobFullName": "deploy-network-config", "buildNumber": 42 }
   

4. Check queue status — Use getQueueItem to inspect queued build requests — waiting reason, position, estimated start time.

   Tool: getQueueItem
   Parameters: { "queueId": 1234 }
   

5. View pipeline run history — Use getPipelineRuns to list pipeline execution history with status, duration, and branch info.

   Tool: getPipelineRuns
   Parameters: { "jobFullName": "deploy-network-config" }
   

Example Prompts

• "Show me all Jenkins jobs"
• "What is the status of the last build for deploy-network-config?"
• "List all failed builds for job network-validation"
• "Are there any builds waiting in the queue?"
• "Show pipeline run history for deploy-network-config"

---

Workflow 2: Build Triggering and Tracking (US2)

Trigger new builds with parameters, track queue-to-build progression, and update build metadata. All write operations require operator confirmation.

Steps

1. Verify job exists and check parameters — Use getJob to confirm the job exists and inspect its parameter definitions before triggering (read-before-write, Constitution II).

   Tool: getJob
   Parameters: { "fullName": "deploy-network-config" }
   → Returns parameter definitions: BRANCH (String), DRY_RUN (Boolean), ENVIRONMENT (Choice)
   

2. Present parameters and confirm with operator — Display the job's parameter definitions and proposed values. Wait for explicit operator approval before proceeding (Constitution XIV — Human-in-the-Loop).

   Confirmation prompt:
   "Ready to trigger build for 'deploy-network-config' with parameters:
    - BRANCH: main (String)
    - DRY_RUN: true (Boolean)
    - ENVIRONMENT: staging (Choice: [dev, staging, prod])
   Proceed? [yes/no]"
   

3. Trigger the build — Use triggerBuild with the confirmed parameters. Supported parameter types: String, Boolean, Choice, Text, Password, Run.

   Tool: triggerBuild
   Parameters: {
     "jobFullName": "deploy-network-config",
     "parameters": [
       { "name": "BRANCH", "value": "main" },
       { "name": "DRY_RUN", "value": "true" },
       { "name": "ENVIRONMENT", "value": "staging" }
     ]
   }
   → Returns queue item ID
   

4. Track queue progression — Use getQueueItem to monitor until the build starts, then switch to getBuild.

   Tool: getQueueItem
   Parameters: { "queueId": <returned-queue-id> }
   → When build starts, returns build number
   

5. Monitor build until completion — Use getBuild to poll build status until result is available.

   Tool: getBuild
   Parameters: { "jobFullName": "deploy-network-config", "buildNumber": <build-number> }
   → Result: SUCCESS | FAILURE | UNSTABLE | ABORTED | NOT_BUILT
   

6. Update build metadata (optional) — Use updateBuild to set a descriptive display name or mark the build as keep-forever. Requires confirmation.

   Tool: updateBuild
   Parameters: {
     "jobFullName": "deploy-network-config",
     "buildNumber": <build-number>,
     "displayName": "Production Deploy - v2.4.1",
     "keepLog": true
   }
   

Example Prompts

• "Trigger a build for deploy-network-config with BRANCH=main"
• "Start job network-validation with DRY_RUN=true and ENVIRONMENT=staging"
• "Mark build #42 of deploy-network-config as keep-forever"
• "Track queue item 1234 until the build completes"

---

Workflow 3: Build Log Analysis (US3)

Retrieve and search build logs for troubleshooting failed builds, identifying errors, and diagnosing pipeline issues.

Steps

1. Retrieve build log — Use getBuildLog with job name and build number. For large logs, use the start offset parameter for pagination.

   Tool: getBuildLog
   Parameters: { "jobFullName": "deploy-network-config", "buildNumber": 42 }
   → Returns console output text
   

2. Paginate large logs — If the log is truncated, use the start offset to retrieve subsequent sections.

   Tool: getBuildLog
   Parameters: { "jobFullName": "deploy-network-config", "buildNumber": 42, "start": 50000 }
   → Returns output starting from byte offset 50000
   

3. Search logs by pattern — Use searchBuildLog with a regex pattern to find specific lines (errors, warnings, timeouts).

   Tool: searchBuildLog
   Parameters: {
     "jobFullName": "deploy-network-config",
     "buildNumber": 42,
     "pattern": "ERROR|FATAL|Exception"
   }
   → Returns matching log lines
   

4. Retrieve pipeline-specific logs — Use getPipelineRunLog for pipeline jobs that produce structured run logs.

   Tool: getPipelineRunLog
   Parameters: { "jobFullName": "deploy-network-config", "runId": "42" }
   

Example Prompts

• "Show me the build log for deploy-network-config build #42"
• "Show the last 100 lines of the build log for network-validation #15"
• "Search the build log for 'ERROR' in deploy-network-config build #42"
• "Find timeout messages in the latest build of network-validation"
• "Show the pipeline log for deploy-network-config run #42"

Handling Large Logs

Build logs can be very large (hundreds of MB for verbose builds). Guidelines:

• Start with searchBuildLog to find relevant sections before retrieving the full log
• Use start offset pagination to retrieve specific sections
• For troubleshooting, search for ERROR, FATAL, Exception, FAILURE, or timeout first

---

Workflow 4: SCM Change Tracking (US4)

Track source code changes associated with Jenkins jobs and builds — correlate builds with commits, find jobs by repository, and review change history.

Steps

1. Get job SCM configuration — Use getJobScm to view the repository URL, branch spec, and polling configuration for a job.

   Tool: getJobScm
   Parameters: { "jobFullName": "deploy-network-config" }
   → Returns: repository URL, branches, credential ID, polling config
   

2. Get build SCM details — Use getBuildScm to see the exact revision (commit hash) and branch checked out for a specific build.

   Tool: getBuildScm
   Parameters: { "jobFullName": "deploy-network-config", "buildNumber": 42 }
   → Returns: revision hash, branch name at build time
   

3. List change sets (commits) — Use getBuildChangeSets to see all commits included in a build — author, message, timestamp, and affected files.

   Tool: getBuildChangeSets
   Parameters: { "jobFullName": "deploy-network-config", "buildNumber": 42 }
   → Returns: list of change sets with commit details
   

4. Find jobs by repository — Use findJobsWithScmUrl to discover all Jenkins jobs configured to build from a specific repository.

   Tool: findJobsWithScmUrl
   Parameters: { "scmUrl": "https://github.com/org/network-configs" }
   → Returns: list of jobs using this repository
   

Example Prompts

• "What repository does deploy-network-config use?"
• "Show me the commits in build #42 of deploy-network-config"
• "Which commit triggered build #42?"
• "Find all Jenkins jobs that use the network-configs repository"
• "What files changed in the latest build of deploy-network-config?"

---

Workflow 5: Health Check and Setup Verification (US5)

Verify Jenkins connectivity, authentication, and instance health. Recommended as a pre-flight check before first use and as a diagnostic tool when other operations fail.

Steps

1. Verify authentication — Use whoAmI to confirm the connection works and inspect the authenticated user's identity and permissions.

   Tool: whoAmI
   Parameters: {}
   → Returns: user name, authorities/permissions list
   

2. Check instance health — Use getStatus to verify Jenkins is healthy and operational.

   Tool: getStatus
   Parameters: {}
   → Returns: mode (NORMAL/SHUTDOWN), version, quietingDown status
   

When to Use

• First-time setup: Run both whoAmI and getStatus to validate the connection
• Authentication failures: Run whoAmI to diagnose credential issues
• Unexpected errors: Run getStatus to check if Jenkins is shutting down or in maintenance mode
• Permission problems: Run whoAmI to verify the user has required authorities

Example Prompts

• "Check my Jenkins connection"
• "Who am I on Jenkins?"
• "Is Jenkins healthy?"
• "Verify Jenkins is running and I have access"

---

GAIT Audit Logging

All Jenkins interactions are logged to the GAIT audit trail via gait_mcp tools at the skill invocation level (per Constitution IV — GAIT Audit Trail).

Logging Pattern

For each Jenkins operation:

1. Before invocation: Log the tool name and parameters being sent

   gait_mcp.log_action({
     action: "jenkins_tool_call",
     tool: "getJobs",
     parameters: { "nameFilter": "deploy-.*" },
     status: "initiated"
   })
   

2. After invocation: Log the result summary

   gait_mcp.log_action({
     action: "jenkins_tool_call",
     tool: "getJobs",
     result_summary: "Returned 12 jobs matching filter",
     status: "completed"
   })
   

3. For write operations: Log the confirmation step

   gait_mcp.log_action({
     action: "jenkins_write_confirmation",
     tool: "triggerBuild",
     parameters: { "jobFullName": "deploy-network-config", "parameters": [...] },
     operator_confirmed: true,
     status: "approved"
   })
   

What Gets Logged

• Tool name and parameters for every invocation
• Result summary (success/failure, record count, key identifiers)
• Operator confirmation for write operations
• Error details when operations fail

---

Integration with Other Skills

• suzieq-observability: After a network deployment build completes, use SuzieQ to validate network state post-change
• aci-change-deploy: Coordinate ACI changes with Jenkins pipeline execution — trigger build after change approval
• gitlab-devops: Correlate GitLab merge requests with Jenkins builds via SCM change tracking
• canvas-a2ui: Visualize build status trends and pipeline health in network dashboards
• gait_mcp: All Jenkins operations are audit-logged for compliance and traceability

---

Important Rules

1. Read-before-write: Always use getJob to verify a job exists and inspect its parameters before triggerBuild or updateBuild
2. Human-in-the-loop: All write operations require explicit operator confirmation — never auto-trigger builds
3. Folder-aware job names: Jenkins jobs in folders use path notation (e.g., folder1/folder2/job-name) — always use the full name
4. Parameterized builds: Check parameter definitions via getJob before triggering — pass correct types (String, Boolean, Choice, Text, Password, Run)
5. Large log handling: Use searchBuildLog before full log retrieval to avoid overwhelming context with large console output
6. GAIT logging: Every Jenkins tool invocation must be logged to the audit trail
7. Credential safety: Never log or display raw API tokens — credentials are managed via environment variables (Constitution XIII)
8. Remote server: This MCP server is a remote HTTP service — connectivity depends on network access to the Jenkins instance