# Jenkins Manager

> >

- **Type:** Skill
- **Install:** `agentstack add skill-sagy101-dotskills-jenkins-manager`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sagy101](https://agentstack.voostack.com/s/sagy101)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sagy101](https://github.com/sagy101)
- **Source:** https://github.com/sagy101/DotSkills/tree/main/jenkins-manager

## Install

```sh
agentstack add skill-sagy101-dotskills-jenkins-manager
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 base_url, credentials, and job_cache:

```json
{
  "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:
```json
{
  "instances": {
    "ci": {
      "job_cache": {
        "my-service": "API/my-service"
      }
    }
  }
}
```

## Pre-flight checks

Run the preflight script before any other operation:

```bash
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):

```bash
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
```

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 ` 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

```bash
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

```bash
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

```bash
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

```bash
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)

```bash
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

```bash
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

```bash
python3 /scripts/list_folders.py
python3 /scripts/list_folders.py --format json
```

### List jobs

```bash
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](https://github.com/sagy101)
- **Source:** [sagy101/DotSkills](https://github.com/sagy101/DotSkills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-sagy101-dotskills-jenkins-manager
- Seller: https://agentstack.voostack.com/s/sagy101
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.