Jenkins Manager

Check build status, view logs, trigger builds, and list jobs on any Jenkins instance.

When to use this skill

Use when the user wants to:

• Check build status for a job or branch
• View Jenkins console output / build logs
• Trigger a Jenkins build (with optional parameters)
• View changes — see which commits are included in a build
• Check queue — see if a triggered build is queued, blocked, or started
• List jobs across organization folders
• List top-level folders and job types
• Discover which Jenkins job corresponds to the current repo

Prerequisites

1. Config: .jenkins.json in project root and/or ~/.jenkins.json for global defaults (see CONFIG.md)
2. Credentials: Per-instance env vars (e.g. JENKINS_USER/JENKINS_TOKEN for CI, JENKINS_CD_TOKEN for CD) exported in shell profile or in a .env file

No pip install or venv needed — all scripts use Python stdlib only.

Config is auto-discovered — scripts search CWD upward, then ~/.jenkins.json. If both exist, they are deep-merged (project-level wins). No --config flag needed.

Config uses named instances — each instance has its own base_url, credentials, and job_cache:

{
  "instances": {
    "ci": {
      "base_url": "https://jenkins-ci.us1.example.com",
      "description": "CI builds for all services",
      "credentials": {
        "username_env": "JENKINS_USER",
        "token_env": "JENKINS_TOKEN"
      }
    },
    "cd-stg": {
      "base_url": "https://jenkins-cd.stg.example.com",
      "description": "CD deployments to staging",
      "credentials": {
        "username_env": "JENKINS_USER",
        "token_env": "JENKINS_CD_TOKEN"
      }
    }
  },
  "default_instance": "ci",
  "env_file": "/path/to/.env"
}

Then a minimal per-project .jenkins.json only needs optional overrides:

{
  "instances": {
    "ci": {
      "job_cache": {
        "my-service": "API/my-service"
      }
    }
  }
}

Pre-flight checks

Run the preflight script before any other operation:

python3 <skill_dir>/scripts/jenkins_preflight.py

This checks Python version, config file, credentials, connectivity, repo detection, and job discovery in one pass. Each check prints [PASS], [FAIL], or [WARN] with actionable fix instructions. Exit code 0 = all checks passed, 1 = at least one failed.

Skip the connectivity and discovery checks (faster, offline-safe):

python3 <skill_dir>/scripts/jenkins_preflight.py --skip-connectivity

If any check fails, fix the issue and re-run before proceeding.

Config setup flow

When no config exists, or the user asks to add a Jenkins instance:

1. Ask the user how many Jenkins instances they have and collect for each: name, base URL, description, username env var, token env var
2. Ask which instance should be the default
3. Before writing the config, show a summary table for approval:

| Instance | URL                                     | Description           | User Env       | Token Env          |
|----------|-----------------------------------------|-----------------------|----------------|--------------------|
| ci       | https://jenkins-ci.us1.example.com      | CI builds             | JENKINS_USER   | JENKINS_TOKEN      |
| cd-stg   | https://jenkins-cd.stg.example.com      | STG deployments       | JENKINS_USER   | JENKINS_CD_TOKEN   |

Default instance: ci

4. After user approval, write ~/.jenkins.json
5. Run preflight to verify connectivity to all instances

When adding a new instance to an existing config: read the current config, ask for the new instance details, show the updated table, and write after approval.

Instance awareness

When the config is loaded, the agent should be aware of which Jenkins instances are available and their descriptions. The --instance flag selects which instance to use. If the user mentions a specific Jenkins (e.g. "check the CD build on stg"), match it to the right instance by description.

Workflow

1. Pre-flight — run checks above
2. Select instance — use --instance <name> if the user specifies one, otherwise the default is used
3. Determine operation — status / logs / trigger / list
4. Plan — for trigger: show plan with --dry-run and wait for user approval
5. Execute — run the appropriate script
6. Verify — offer to check status or view logs after trigger operations

Operations

Check build status

python3 <skill_dir>/scripts/get_status.py
python3 <skill_dir>/scripts/get_status.py --instance cd-stg
python3 <skill_dir>/scripts/get_status.py --build 1094
python3 <skill_dir>/scripts/get_status.py --folder MyFolder --job my-service --branch main
python3 <skill_dir>/scripts/get_status.py --format json
python3 <skill_dir>/scripts/get_status.py --watch --interval 30 --timeout 300
python3 <skill_dir>/scripts/get_status.py --build 1094 --watch

Auto-resolves folder, job, and branch from git remote + current branch. Override with flags.

Flags: --build N (specific build number, default: last build), --watch (poll until build finishes), --interval N (poll interval in seconds, default 60), --timeout N (max wait in seconds, default 600). Watch mode exit codes: 0=success, 1=build failed, 2=timeout.

View build logs

python3 <skill_dir>/scripts/get_logs.py
python3 <skill_dir>/scripts/get_logs.py --tail 50
python3 <skill_dir>/scripts/get_logs.py --grep "ERROR"
python3 <skill_dir>/scripts/get_logs.py --build 142 --tail 0
python3 <skill_dir>/scripts/get_logs.py --folder MyFolder --job my-service --branch main

Flags: --tail N (default 100, 0 for all), --grep PATTERN (regex filter), --build N (specific build number).

All log output is redacted — secrets (API keys, tokens, passwords, AWS keys, connection strings, private keys, JWTs) are scrubbed before display. ANSI escape codes (color, bold, etc.) are automatically stripped before redaction and grep matching.

View test results

python3 <skill_dir>/scripts/get_test_results.py
python3 <skill_dir>/scripts/get_test_results.py --build 142
python3 <skill_dir>/scripts/get_test_results.py --failures-only
python3 <skill_dir>/scripts/get_test_results.py --format json

Shows structured test results from JUnit reports: totals (pass/fail/skip) and failed test details (suite, test name, error message). Works with any language/framework that produces JUnit XML. Gracefully handles 404 when JUnit plugin is not installed.

Flags: --build N (specific build number), --failures-only (show only failed tests), --format json.

Trigger a build

python3 <skill_dir>/scripts/trigger_build.py --dry-run
python3 <skill_dir>/scripts/trigger_build.py --folder MyFolder --job my-service --branch feature/my-branch --dry-run
python3 <skill_dir>/scripts/trigger_build.py --parameters ENV=staging VERSION=1.2.3 --dry-run

Remove --dry-run after review. Supports parameterized builds with --parameters KEY=VALUE.

View build changes (commits)

python3 <skill_dir>/scripts/get_changesets.py
python3 <skill_dir>/scripts/get_changesets.py --folder MyFolder --job my-service --branch main
python3 <skill_dir>/scripts/get_changesets.py --build 142
python3 <skill_dir>/scripts/get_changesets.py --format json

Shows commits included in a build: short SHA, author, message, and affected file count. Defaults to the latest build.

Check queue status

python3 <skill_dir>/scripts/get_queue_item.py --queue-id 12345
python3 <skill_dir>/scripts/get_queue_item.py --queue-id 12345 --format json

Shows whether a queued build is waiting, blocked, stuck, or has started. Use the queue ID returned after triggering a build.

List top-level folders

python3 <skill_dir>/scripts/list_folders.py
python3 <skill_dir>/scripts/list_folders.py --format json

List jobs

python3 <skill_dir>/scripts/list_jobs.py
python3 <skill_dir>/scripts/list_jobs.py --folder MyFolder
python3 <skill_dir>/scripts/list_jobs.py --name "my-service"
python3 <skill_dir>/scripts/list_jobs.py --format json

Flags: --folder (search specific folder), --name PATTERN (regex/substring filter).

Common flags (all scripts)

All scripts accept --instance <name> (selects Jenkins instance), --job <name> (auto-detected from git remote if omitted), --folder <name> (auto-discovered if omitted), --branch <name> (auto-detected from current git branch if omitted), and --config <path> (auto-discovered if omitted).

Important rules

1. ALWAYS use the provided scripts. Every operation has a dedicated script. Run them via python3 <skill_dir>/scripts/<script>.py. NEVER write inline Python to call JenkinsClient, jenkins_config, or the Jenkins REST API directly. The scripts handle auth, config merging, error formatting, job auto-discovery, secret redaction, and branch encoding.
2. If a script fails, debug the script invocation (wrong flags, missing config, missing credentials). Do NOT abandon the scripts and write custom code. Check the error table below and re-run with corrected arguments.
3. Never trigger a build without --dry-run first + explicit user approval.
4. Never print credentials. Only confirm env vars are set.
5. Job is auto-discovered from git remote. Override with --folder and --job if needed.
6. All log output is redacted. Secret patterns are scrubbed before display. Do not attempt to bypass redaction.

Error handling

Troubleshooting