Jenkins Manager

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](references/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 baseurl, credentials, and jobcache:

{
  "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 /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 /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

1. After user approval, write ~/.jenkins.json
2. 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 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 /scripts/get_status.py
python3 /scripts/get_status.py --instance cd-stg
python3 /scripts/get_status.py --build 1094
python3 /scripts/get_status.py --folder MyFolder --job my-service --branch main
python3 /scripts/get_status.py --format json
python3 /scripts/get_status.py --watch --interval 30 --timeout 300
python3 /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 /scripts/get_logs.py
python3 /scripts/get_logs.py --tail 50
python3 /scripts/get_logs.py --grep "ERROR"
python3 /scripts/get_logs.py --build 142 --tail 0
python3 /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 /scripts/get_test_results.py
python3 /scripts/get_test_results.py --build 142
python3 /scripts/get_test_results.py --failures-only
python3 /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 /scripts/trigger_build.py --dry-run
python3 /scripts/trigger_build.py --folder MyFolder --job my-service --branch feature/my-branch --dry-run
python3 /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 /scripts/get_changesets.py
python3 /scripts/get_changesets.py --folder MyFolder --job my-service --branch main
python3 /scripts/get_changesets.py --build 142
python3 /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 /scripts/get_queue_item.py --queue-id 12345
python3 /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 /scripts/list_folders.py
python3 /scripts/list_folders.py --format json

List jobs

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

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

Common flags (all scripts)

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

Important rules

1. ALWAYS use the provided scripts. Every operation has a dedicated script. Run them via python3 /scripts/.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

| Error | Cause | Fix | |---|---|---| | 401 Unauthorized | Bad credentials | Verify JENKINS_USER and JENKINS_TOKEN env vars. Token must be a Jenkins API token, not account password | | 403 Forbidden | Insufficient permissions or CSRF issue | Check user permissions. For POST operations, CSRF crumb is handled automatically | | 404 Not Found | Wrong folder, job, or branch name | Verify with list_folders.py and list_jobs.py. Branch names are URL-encoded automatically | | 500 Internal Server Error | Jenkins server error | Check Jenkins server health. Retry after a moment | | SSL certificate verification failed | Self-signed cert or custom CA | Set ssl_verify: false in config, or set SSL_CERT_FILE env var | | Config not found | No .jenkins.json anywhere | Create ~/.jenkins.json with instances — see config setup flow | | Instance not found | Wrong --instance name | Check available instances in config or run preflight | | Job not found | Auto-discovery failed | Add job_cache entry to the instance in .jenkins.json, or use --folder + --job | | env_file escapes project root | Relative env_file in global config | Use an absolute path for env_file in global ~/.jenkins.json | | env_file not found | Path in config doesn't exist | Check the env_file path in config; use absolute path in global config |

Troubleshooting

| Problem | Fix | |---|---| | python3: command not found | Install Python 3.10+ | | Can't detect repo from git remote | Provide --job explicitly | | Can't find job in Jenkins | Run list_jobs.py --name to search; add result to job_cache | | Build trigger returns 403 | User may lack build permissions. Check Jenkins user roles | | Console log is huge/slow | Use --tail 50 or --grep "ERROR" to filter | | Branch name with / not found | Branch encoding is automatic; verify branch exists with list_jobs.py --folder F --name J | | SSL errors on corporate Jenkins | Set "ssl_verify": false in .jenkins.json |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sagy101
• Source: sagy101/DotSkills
• License: MIT

Install and usage instructions live in the source repository linked above.