Batch Control

Korean translation: README.ko.md

Run approval, time-boxed change permissions and an append-only audit history for Jenkins instances that are operated as a batch execution manager rather than as a CI server.

It is for teams whose nightly and periodic production workload runs on Jenkins, where starting a job by hand or changing what it does is an operational change. Installing the plugin changes nothing by itself: both controls are off until an administrator turns them on.

• Run approval. A person's manual run of a protected job (Build Now, REST, CLI, Replay) is refused at queue entry and becomes a run request. Only the designated approvers may decide it, and the approved build gets exactly the parameters they saw, once.
• Activation. A job created while run control is on does not run on a timer, upstream trigger, SCM trigger or webhook until an approver activates it. Existing jobs keep their schedules.
• Permission windows. A user without standing rights requests CREATE, CONFIGURE or DELETE on one job or folder for a limited time; the window closes by itself.
• Audit history independent of builds. Runs, requests, decisions, configuration changes with diffs, and failures are kept append-only under $JENKINS_HOME/batch-control/, with history screens and CSV export.
• Incidents. Failed and unstable runs open an incident (the default; aborted runs can be added in the settings) with the last 100 console lines, to acknowledge, resolve and rerun through a request.
• Fits your security setup. Works through Batch Control variants of Matrix Authorization Strategy and Role-based Authorization Strategy; e-mail notifications (off by default); configurable with Configuration as Code.

The frames drawn on each screenshot mark where to look.

Administrator: turns on run control, change control or both, and lists the approvers.

Requester: chooses Request Run on a job that requires approval, gives a reason and picks the approvers.

Approver: reads the reason and the parameters, then chooses Approve or Reject.

Anyone with the BatchControl/ViewHistory permission: finds that request in History and sees who asked, who decided and that it ran.

Requester: requests a permission window, here CONFIGURE on one job for 60 minutes, and gives a reason.

Approver: reads the request, then chooses Approve or Reject. An approved window closes by itself when the time is up.

• Jenkins 2.568.3 or newer on Java 21 or 25.
• Required plugins: cloudbees-folder, ionicons-api and caffeine-api, resolved for you on installation.
• An authorization strategy that draws a permission matrix, such as Matrix Authorization Strategy or Role-based Authorization Strategy; the Batch Control permissions cannot be assigned on "Logged-in users can do anything".

Batch Control loads without these plugins; if one is installed, it must be at least this version:

With an older version installed Batch Control does not load. Plugins → Available plugins offers the upgrade; Deploy Plugin does not, so upgrade first.

Install from Manage Jenkins → Plugins → Available plugins (search for Batch Control), or upload a build under Advanced settings → Deploy Plugin. Building needs Maven and JDK 21 or 25: mvn clean package produces target/batch-control.hpi.

1. In Manage Jenkins → System → Batch Control, check Enable run control (and Enable change control for permission windows), list the approvers' user IDs under Approvers, and save.
2. For change control only, select the Batch Control strategy: the monitor on Manage Jenkins offers Install the Batch Control variant (details).
3. Give requesters BatchControl/Request and approvers BatchControl/Approve, both with Overall/Read and Item/Read.
4. On a job, check Require approval to run (section Batch Control).
5. The requester chooses Request Run on the job, fills in the parameters, a reason and the approvers, and submits.
6. The approver opens Batch Control (in the ☰ menu) → Run Requests and chooses Approve or Reject. On approval the build is queued.

Jobs created while run control is on need an approved activation before they run unattended (Activation). The full setup is in the user guide.

The full rules.

• User guide: how both controls work, configuration, the screens, notifications, and the limitations that change decisions.
• Known limitations: the complete list.
• Issues and feature requests: https://github.com/jenkinsci/batch-control-plugin/issues.

Issues and pull requests are welcome; CONTRIBUTING.md is the guide. docs/SPEC.md is the functional contract (if the code and the spec disagree, the code is wrong); it, docs/DECISIONS.md and docs/ARCHITECTURE.md are written largely in Korean, with the newer sections in English.

Please do not open a GitHub issue. Report privately in the Jenkins SECURITY project under the specific-plugin component, naming the plugin in the summary, or mail jenkinsci-cert@googlegroups.com. Full policy: https://www.jenkins.io/security/reporting/.

MIT. See LICENSE.