Jenkins Remote Port

Purpose

This is the Harbor reference integration for the Jenkins Remote API.

Use it when:

• building Jenkins actions in Harbor
• extending the Dock / Hub Jenkins entry
• teaching Codex or OpenClaw how to map CI job inspection and bounded trigger flows into Harbor Ports and Harbor Actions without turning Harbor into a generic Jenkins admin proxy

Harbor Port worksheet

Product

• Product: Jenkins Remote API
• Publisher slug: jenkins
• Publisher name: Jenkins
• Category: Developer Tools
• Tags: jenkins, ci, builds, jobs, automation

Safe Harbor Port metadata

• Kind: http_api
• Label: Jenkins Remote API
• Description: Jenkins Remote API connection managed locally through Harbor.
• Base URL: tenant-specific Jenkins controller root, for example https://ci.example.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Basic

Hidden local config

• authToken

Harbor stores the credential locally only. Dock / Hub manifests must never contain it.

For Jenkins, the Harbor auth token should be the base64-encoded username:apiToken value because Harbor emits Authorization: Basic <token> for this auth mode.

Harbor action design notes

Jenkins is a good Harbor fit when we keep job paths explicit, build reads bounded, and triggers reviewable.

Good Harbor Jenkins starter actions:

• fixed GET reads for controller job inventory
• a bounded GET build-inspection route for a known job and build ref
• one reviewable POST route for non-parameterized job triggering
• requestBodyMode: "none" for all starter actions
• resultMode: "json_summary" for all starter actions

Avoid for now:

• generic job creation, copy, delete, or config.xml mutation flows
• parameterized build passthroughs before stronger body-shaping support exists
• folder-recursive arbitrary path execution surfaces
• plugin, node, credential, or global-admin endpoints

Starter Jenkins actions

Automatic read actions

• list-jobs -> GET /api/json
• get-build -> GET /job/{jobName}/{buildRef}/api/json

Approval-friendly write actions

• trigger-job -> POST /job/{jobName}/build

Why these actions

These routes fit Harbor's current safe model because they:

• stay on stable REST-like Jenkins API endpoints under one explicit controller base URL
• keep targeting explicit through bounded path templates rather than arbitrary route forwarding
• use static field selection via the tree query to avoid pulling the entire controller model by default
• expose job triggering as a named capability instead of generic authenticated HTTP access

Action Model notes

At execution time, callers supply values by location:

• input.query.depth for list-jobs
• input.path.jobName and input.path.buildRef for get-build
• input.path.jobName for trigger-job

Example job listing request:

{
  "query": {
    "depth": 1
  }
}

Example build lookup request:

{
  "path": {
    "jobName": "release-main",
    "buildRef": "lastSuccessfulBuild"
  }
}

Example trigger request:

{
  "path": {
    "jobName": "release-main"
  }
}

These starter templates intentionally target top-level jobs only. If Harbor later grows a clearer safe model for nested Jenkins folder paths, that can be added deliberately instead of overloading this first pass.

Safety note for triggers

trigger-job stays on require_approval because even a non-parameterized Jenkins build can deploy code, rotate infrastructure, or mutate downstream systems. Harbor should treat that as an explicit, reviewable capability.

Suggested operator workflow

1. Import the Jenkins Dock entry from Dock / Hub.
2. Configure the local Jenkins controller base URL in Harbor Node.
3. Configure the local Jenkins Authorization credential as a base64 username:apiToken value.
4. Use list-jobs to discover available CI jobs.
5. Use get-build to inspect recent build state before enabling trigger-job.
6. Keep trigger-job on require_approval unless there is a very clear local policy reason not to.

Suggested agent workflow

1. Inspect the existing Jenkins Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed Jenkins routes only when they remain bounded and reviewable.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored Jenkins credential
• widen Jenkins into a generic controller administration proxy
• add parameterized or config-mutating job flows without review
• hide job targeting behind arbitrary path input

Current update strategy

For now, Jenkins updates are manual:

• update the Dock / Hub Jenkins integration document in apps/hub/catalog/integrations/jenkins/jenkins-remote-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Official reference starting points

• Jenkins Remote Access API overview: https://www.jenkins.io/doc/book/using/remote-access-api/
• Authenticating scripted clients: https://www.jenkins.io/doc/book/system-administration/authenticating-scripted-clients/
• Jenkins top-level API example: https://ci.jenkins.io/api/
• Jenkins build API example: https://ci.jenkins.io/job/Websites/job/jenkins.io/job/master/lastSuccessfulBuild/api/