kits-jenkins

Download Jenkins workspaces with hidden files and configurable dependency filtering. Use the Codex plugin, install the standalone skill, or run the Python CLI directly.

The plugin is named kits-jenkins and provides the jenkins-workspace skill. Give it a Jenkins project or workspace URL; the CLI handles authentication, directory traversal, filtering, downloads and verification.

Requirements

Python 3.9 or later and access to the Jenkins workspace.
A Jenkins API token, a locally configured session cookie, or a signed-in browser with the Kimi browser extension and local bridge.
Git for optional repository integrity checks with --verify-git.

No OpenAI API key is required. Browser authentication is optional; API token authentication works without a browser.

Quick Start

Codex Plugin

The repository root is an installable plugin source. Marketplace maintainers can use the example catalog entry to reference this repository directly. See Marketplace Distribution for Git references, pinned versions and local ZIP distribution.

After installing the plugin in Codex, ask:

Use $jenkins-workspace to download https://jenkins.example/job/team/job/pay/ without dependencies or build artifacts.

The skill uses source mode by default, preserves hidden files and reports the resulting ZIP and extracted directory. Specify that you want the full workspace to include dependencies, caches and artifacts.

Standalone Skill

From a checkout of this repository, install with uv:

uv run --with . --no-project jenkins-workspace install-skill

Or use a virtual environment:

python3 -m venv venv
venv/bin/python -m pip install .
venv/bin/jenkins-workspace install-skill

On Windows, use venv/Scripts/ instead of venv/bin/. The default skill destination is $CODEX_HOME/skills/jenkins-workspace, with ~/.codex as the default CODEX_HOME. To use the user-level agent skill directory instead, pass --destination ~/.agents/skills/jenkins-workspace. Choose one installation source to avoid duplicate skill discovery.

The installation is self-contained and does not depend on the checkout staying in place. On first use, the launcher installs missing Python dependencies into $CODEX_HOME/local/jenkins-workspace/venv; this requires network access. Restart Codex if the new skill is not yet available.

An existing installation is preserved unless you use install-skill --update. Updates back up the previous installation under $CODEX_HOME/local/jenkins-workspace/backups/ and restore it if replacement fails. Local edits remain in the backup; they are not merged into the new installation.

CLI

The same package provides a CLI that runs independently of any agent:

venv/bin/jenkins-workspace doctor --json
venv/bin/jenkins-workspace inspect 'https://jenkins.example/job/team/job/pay/' --auth browser --json
venv/bin/jenkins-workspace download 'https://jenkins.example/job/team/job/pay/ws/' --auth browser --verify-git

With the environment activated, use jenkins-workspace directly. You can also run python -m jenkins_workspace or, from a source checkout, python skills/jenkins-workspace/scripts/run.py.

Download Options

Command or option	Behavior
`doctor`	Check Python, Git, the browser bridge and token configuration without displaying credentials
`inspect URL`	Check the URL, authentication and root directory; show the project type and filtering policy
`download URL`	Download, verify, extract and write a report
`--mode source`	Default: exclude installed dependencies, cache contents and packaged artifacts
`--mode full`	Include everything and restore hidden files omitted from Jenkins ZIPs
`--include-node-modules` / `--exclude-node-modules`	Override dependency installation directory handling
`--include-dependency-caches` / `--exclude-dependency-caches`	Override cache handling; excluded caches remain as empty directories
`--include-build-artifacts` / `--exclude-build-artifacts`	Override artifact filtering
`--cache-dir PATH`	Replace the default cache rules; repeat for multiple relative paths
`--artifact-suffix SUFFIX`	Replace the default artifact suffixes; repeat for multiple suffixes
`--output DIR`	Set the output parent directory; default: `./jenkins-downloads`
`--zip-only`	Save the ZIP without extraction
`--verify-git`	Run Git integrity checks after extraction; incompatible with `--zip-only`
`--json`	Write one JSON result to stdout and progress to stderr

Default cache paths are .yarn/cache, .npm and .pnpm-store. Default artifact suffixes are .jar, .war, .ear and .jar.original. Explicit include/exclude flags override the selected mode independently.

Cache rules match complete path components at any depth. .yarn/cache-backup is not a match for .yarn/cache; Yarn releases, plugins, patches and lockfiles are preserved. Artifact suffix matching is case-insensitive and also excludes dependency JARs or Maven Wrapper JARs with a matching suffix. Files such as .class and .jar.sha256 are retained by default. Source mode is a filtered workspace snapshot, not a pure Git source export.

More examples are in Download Options.

Authentication and Results

--auth auto checks complete JENKINS_USER and JENKINS_API_TOKEN configuration first, then an explicitly configured cookie, then a browser session. Select a method with --auth browser|token|cookie|none. Use --env-file /path/to/private.env to load a local credentials file explicitly; the CLI does not automatically read .env from the current directory.

Browser mode reads only cookies applicable to the selected Jenkins site and keeps them in process memory. Its tabs remain open. Expired sessions return AUTH_REQUIRED; bridge connection problems return BROWSER_UNAVAILABLE. See Authentication and Recovery. Do not put credentials in command arguments, chat, source control or reports.

Each download creates a new run directory containing the ZIP, the extracted project unless --zip-only is set, and report.json. Reports contain filters, skipped items, file counts, size, SHA-256 and verification status. The CLI compares the ZIP contents with directory listings collected during download. Failures return a nonzero exit code and mark the run incomplete. There is no cross-process download resume; retrying creates another directory and preserves earlier results.

How Downloads Work

Jenkins ZIP downloads use Ant default exclusions that can omit .git, .gitignore and other hidden files. The downloader uses *plain* directory listings to discover and restore omitted entries, including nested hidden files.

When any exclusion is enabled, the downloader traverses directories and selects files before transferring them. It does not request recursive ZIPs that could contain excluded content. Cache roots are written as empty directory entries. If a directory contains excluded artifacts, retained files are downloaded individually; other small directories can use a ZIP of direct files only. Directories with more than 100 files and interrupted direct-file ZIP transfers fall back to individual file requests.

ZIPs are assembled in temporary files and verified before replacing their destination. Authentication, listing and download failures stop extraction. Symbolic links are unsupported, and the tool can only read files that Jenkins permits. Avoid downloading while a build is changing the workspace.

Source Layout

kits-jenkins/
|-- plugin.json                    Generated portable plugin manifest
|-- .codex-plugin/plugin.json      Generated Codex compatibility manifest
|-- src/jenkins_workspace/         Canonical CLI and download implementation
|   `-- plugin.py                 Canonical plugin metadata and manifest generator
|-- skills/jenkins-workspace/      Canonical skill instructions and launcher
|   |-- SKILL.md
|   |-- agents/openai.yaml
|   |-- references/
|   `-- scripts/run.py
|-- tests/
|-- docs/marketplace.md
|-- examples/marketplace-entry.json
|-- .github/workflows/validate.yml
|-- pyproject.toml
|-- requirements.txt              Canonical dependency constraints
`-- dist/                         Generated artifacts, ignored by Git

The skill selects options and handles authentication prerequisites; the CLI performs the deterministic workflow. Development and Git-installed plugin launchers load src/ directly. Wheel packaging maps the same source and skill directories without maintaining duplicate implementations.

build-plugin, build-skill and install-skill share the assembly implementation. Bundled scripts/jenkins_workspace/ files are generated release snapshots. Each skill bundle includes a bundle.json with its version and file hashes. Edit the canonical sources, not installed copies or generated ZIP contents.

Development and Distribution

venv/bin/python -m pip install -e .
venv/bin/python -m jenkins_workspace.plugin --check
venv/bin/python -B -m unittest discover -s tests -v
venv/bin/python skills/jenkins-workspace/scripts/run.py --version

The version lives in src/jenkins_workspace/__init__.py. Plugin metadata lives in src/jenkins_workspace/plugin.py. After editing either, regenerate the committed manifests and build the release artifacts:

venv/bin/python -m jenkins_workspace.plugin --sync
venv/bin/jenkins-workspace build-plugin
venv/bin/jenkins-workspace build-skill
uv build

CI checks manifest consistency, runs the tests on Python 3.9 and 3.13, and builds the plugin ZIP, skill ZIP, wheel and source distribution. The default ZIP paths are dist/kits-jenkins-plugin.zip and dist/jenkins-workspace-skill.zip. Git-backed marketplaces use the repository root directly and do not require a prebuilt ZIP.

To update a standalone skill after installing a new CLI version, run jenkins-workspace install-skill --update. Plugin installations are updated through Codex plugin management; do not use install-skill to modify a plugin cache.

A standalone skill ZIP can be installed without a source checkout or wheel. For a first installation on macOS/Linux:

mkdir -p ~/.agents/skills
unzip -n jenkins-workspace-skill.zip -d ~/.agents/skills

For an existing ZIP-based installation, extract the new bundle into a temporary directory and run its scripts/run.py install-skill --update --destination EXISTING_SKILL_DIR. Do not merge old and new bundle files manually. Release bundles contain instructions, Python code and dependency constraints; credentials, downloaded workspaces and local environments are excluded.