All Classes and Interfaces
Class
Description
One activation or hold request at
/batch-control/activations/<id>/ (SPEC item 6a),
the URL the notifications link to: detail view plus the state-changing POST endpoints
approve, reject, cancel and changeApprover, following
RequestItem.Keeps the activation store in step with the items (SPEC item 6a): a rename or move keeps the
job's activation under its new full name, a deletion removes it, and a newly created job never
inherits a state left under its name; a job created while run control is off is recorded as
activated (D-45).
A request to put one job into service (
ActivationRequest.Action.ACTIVATE) or to put it on hold
(ActivationRequest.Action.HOLD) (SPEC item 6a, D-39).What the request asks for.
One approver change entry (D-37); same shape as
GrantRequest.ApproverChange.One-time upgrade seeding of activation approval (SPEC item 6a, DESIGN-ACTIVATION-APPROVAL
section 6): jobs that exist when this version is first installed are recorded as activated, so
installing or upgrading never stops an existing schedule.
Activation approval (SPEC item 6a, D-39): whether a run-controlled job may run unattended, and
the single entry point for every
ActivationRequest state transition and every
ActivationState write.The activation request screen at
/batch-control/activations/ (SPEC item 6a, D-66):
the activation and hold requests the viewer may see as pending (those awaiting the viewer's
decision marked), active (the request in effect for its job) and ended, each in pages of
50 (?pendingPage=N, ?activePage=N, ?endedPage=N).Whether a job has been approved to run unattended (SPEC item 6a, D-39).
Read-only display helpers for activation state (SPEC item 6a, D-46), shared by the job page,
the computed-folder page and the activation screens.
Routing object for
/batch-control/grants/active/....One active grant; only carries the revoke endpoint.
Approver eligibility rules (SPEC items 2 and 3), shared by
RunRequestService and
GrantRequestService.The queue gate (SPEC item 6, D-03): every run path goes through
Queue.QueueDecisionHandler, so approval-required jobs are controlled at one point.e2e-03 DEF-25 (SPEC item 6 and section 6 usability): the rebuild plugin's Rebuild and Rebuild
Last entries are not offered on builds of a job whose manual runs need an approved run request
(
RunRequestService.requiresApprovalToRun(hudson.model.Job<?, ?>)), because the queue gate refuses every such
rebuild.The refusal of a user-originated manual run of an approval-required job (SPEC item 6, e2e-03
DEF-02), thrown by the queue gate in place of a plain
Failure.Cause carried by every build that runs on behalf of an approved run request (SPEC item 5):
links the build to the request id, the requester and the approver.
Invisible marker action that authorizes exactly one queue submission for an approved run
request (D-23).
D-72b (7), security-35 S-35-07: when the queue item of an approved run (it carries
ApprovedRunAction) is cancelled (by a user, by clearing the queue, or because its job
was deleted), the request records it, so startup recovery never submits that run again and the
request's files are disposed of when it ends.Reads the designated approver set from a submitted form (SPEC item 3, D-37).
Computes the approver candidates shown in request forms: the global approver list intersected
with the job-level restriction when one is configured (SPEC items 3 and 5).
Helpers for a designated approver set (D-37): order-preserving, duplicate-free, trimmed,
blank entries dropped.
Single source of time for the whole plugin.
e2e-03 DEF-10 (SPEC section 6, usability):
BatchControl/Manage is enough to open and
save the Batch Control configuration.Global plugin configuration (SPEC section 5 keys and defaults).
Per-job batch control settings (SPEC items 5 and 6): whether the job requires an approved run
request, trigger-blocking policy, and an optional job-level approver restriction.
matrix-auth's project-based matrix with Batch Control grants layered on top (D-35a,
ARCHITECTURE section 4).
Found by XStream through the
$ConverterImpl naming convention.Listed on the security page.
JCasC support for
BatchControlMatrixAuthorizationStrategy under the symbol
batchControlProjectMatrix, with the same schema as matrix-auth's
projectMatrix (D-35a, PoC-5 row 8).Extension point receiving Batch Control request events (SPEC item 13, D-36).
The five plugin permissions (SPEC item 2), exposed to Matrix/Role authorization strategies as
the "Batch Control" group.
role-strategy's role-based strategy with Batch Control grants layered on top (D-35a,
ARCHITECTURE section 4).
role-strategy's converter is public: the on-disk format is the same, only the type differs.
Listed on the security page.
JCasC support for
BatchControlRoleBasedAuthorizationStrategy under the symbol
batchControlRoleBased, with the same schema as role-strategy's roleBased
(D-35a, PoC-5 row 8).Global "Batch Control" page at
/batch-control."Change control is on, but the installed authorization strategy is not a Batch Control
strategy" (D-35a, ARCHITECTURE section 4).
The single writer of the "an attempt was refused" audit records (
ChangeType.MARKER_REUSE_BLOCKED, ChangeType.REMOTE_RUN_BLOCKED,
ChangeType.TRIGGER_BLOCKED), with a bound on how often one repeated attempt may append
(S-21).Classification of what caused a build, stored in a
RunRecord.D-59: puts
MoveGuard in front of every move the folders plugin performs.Audit record of a change event (SPEC section 3).
The change record list at
/batch-control/changes/ (SPEC item 9).Kind of event captured by a
ChangeRecord.D-40: remembers, on the thread that runs it, the target of a
create-job or
copy-job CLI command, for NewItemName.Activation on a computed folder (multibranch project, organization folder), which carries the
activation of the jobs it generates (D-46c, SPEC item 6a).
Attaches
ComputedFolderActivationAction to every computed folder (D-46c).Records CONFIGURE changes with a unified diff (SPEC item 9) and maintains the per-item config
snapshots (
snapshots/<encoded fullName>.xml, latest only — ARCHITECTURE section 5).Marks the item whose creation (or copy) is being announced on this thread (
ConfigSnapshotListener.ANNOUNCED)
before any other item listener runs, so ConfigSnapshotListener.isCreationSave(hudson.model.Item) can tell a save of the new item
from a save of another item made by a listener of that announcement.Clears the mark of
ConfigSnapshotListener.CreationAnnounced after every other item listener has run (core calls
each listener whatever the previous ones threw).The refresh of every snapshot after change recording was turned on
(
SnapshotSeeding).Marks the save of an item as being reported (
ConfigSnapshotListener.SAVING) before any other save listener
runs, so seeding never takes a baseline from a configuration whose save has not reached
ConfigSnapshotListener yet.Warns administrators when change control cannot actually control changes (SPEC item 8):
change control is on, but either the global authorization strategy is not a Batch Control
strategy (so grants can never apply, D-35a), or some known non-admin user holds
Item/Configure, Item/Create, Item/Delete or Item/Move (D-59) directly from the strategy — a standing change
permission that bypasses the JIT grant process.
One user or group that holds Item/Configure, Item/Create or Item/Delete from the
authorization strategy itself, outside any grant (e2e-03 DEF-07).
D-35c: records in the grant an item that its holder could only create because of the grant's
Create.
The optional name restriction of a CREATE grant (D-40): either an exact item name, or a Java
regular expression written as
/regex/ that must match the whole item name.Minimal CSV emitter for the audit export endpoints (SPEC item 12).
The run record dashboard at
/batch-control/dashboard/ (SPEC item 10): the most recent
builds of every job with cause, user, parameters, result, duration, who aborted it, and — for
APPROVED_REQUEST builds — a link to the originating run request.The plugin's only time-rendering vocabulary (U-07).
Delete veto (SPEC item 8, ARCHITECTURE section 2): with change control on, deleting an item
requires an active DELETE grant — even when the underlying authorization strategy grants
Item/Delete directly.
Who deleted an item (SPEC 6: the history names who did what).
D-66: request forms opened in core's dialog (
data-type="dialog-opener" with
data-dialog-url, the mechanism of core's "Create User" and build-parameters dialogs).One-line size summary of a stored unified diff, for the change-records screen (U-07).
#34: the forced writes every store write goes through, as core's
AtomicFileWriter does
them.The reason texts of requests that end without a decision (e2e-04 FD-05, D-54).
Periodic status refresh for expiry (SPEC items 7 and 8).
The only place where Batch Control uses the optional file-parameters plugin
(
stashedFile, base64File).File-based
Store rooted at $JENKINS_HOME/batch-control/.Parses and validates the history filter query parameters (SPEC item 12):
from, to (ISO dates, inclusive), job (case-insensitive substring of
the full name), user (exact id), result and status (enum-name tokens).The validated filter.
e2e-03 DEF-19 (SPEC item 8, D-40): the folder page tells the holder of a Create window which new
job names the window allows.
Attaches
FolderCreateWindowAction (e2e-03 DEF-19) and FolderGrantRequestAction
(R4-14) to every folder.R4-14 (D-66): the folder counterpart of
JobGrantRequestAction, a "Request Change
Permission" entry on a folder that opens the grant request form prefilled for the folder
(scopeFullName=<folder>).The refusal of a submitted form, rendered on the form itself (SPEC section 6 usability line,
e2e-03 DEF-09): the message sits next to the field it is about and what the user typed is kept.
An approved temporary permission (SPEC item 8, section 3): the result of an approved
GrantRequest.The change actions a JIT grant can cover (SPEC item 8).
Entry points to the grant layer for code outside this package (D-35b, D-35c).
Implemented by the Batch Control authorization strategies, the subclasses of the supported
strategies that layer active grants over the parent's ACLs (D-35a, ARCHITECTURE section 4).
A request for a temporary (JIT) change permission (SPEC item 8, section 3).
One approver change entry of a grant request: (previous set, new set, changed by, at)
(SPEC section 3, D-37).
One grant request at
/batch-control/grants/<id>/: detail view plus the five
state-changing POST endpoints (approve, reject, cancel,
changeApprover and, for its open window, revoke — R4-12).Links to the new grant request form on the Grants screen, prefilled for one item and one
action (U-01 convention:
new?scopeFullName=&actions=, D-66; D-71: a window names exactly
one item, so there is no scope type).The single entry point for every
GrantRequest state transition (SPEC items 3 and 8).The refusal of a change that needs a permission window the user does not hold (SPEC item 8),
for example the delete veto (e2e-03 DEF-26).
Target of a grant request / grant: exactly one item, a job or a folder of any kind (D-71,
replaces the JOB, FOLDER and FOLDER_ONLY scopes of D-65).
Scope kind.
Runtime authority on active grants (SPEC item 8).
The grant screens at
/batch-control/grants/ (SPEC item 8, JIT permission requests).One row of the Grants lists: a grant request and, once approved, its permission window
(the window carries the request's id).
D-35b: a user whose Item/Configure comes only from a grant cannot turn it into a permanent
authorization entry.
Keeps the baseline in step with item lifecycle events, and applies the payload half of
D-35c.
What the strategy monitor says about an item in the "changed under a grant" state
(D-58a/b): which permission window recorded the change, and after "Mark as reviewed" what still
guards the item.
The permission window that recorded a change to an item (or to a folder above it).
What still guards an item after it was marked as reviewed.
The history browser at
/batch-control/history/ (SPEC item 12): filtered listings of
run records, incidents, change records and run requests, a monthly aggregate JSON endpoint,
and CSV exports.HTTP verb guard for the Batch Control URL spaces.
Generates store identifiers.
An automatically registered error case (SPEC items 11 and section 3): opened for every build
whose result is in the configured
incidentResults, then handled by people
(OPEN -> ACKNOWLEDGED -> RESOLVED).One incident at
/batch-control/incidents/<id>/ (SPEC item 11): detail view plus the
four state-changing POST endpoints (acknowledge, resolve, comment,
rerun).The single entry point for every
Incident lifecycle operation (SPEC item 11, D-10,
D-19): automatic registration from completed builds, forward-only handling transitions
(OPEN -> ACKNOWLEDGED -> RESOLVED), comments, rerun requests and the automatic
resolvedByRunId link.The incident list at
/batch-control/incidents/ (SPEC item 11).Handling state of an
Incident (SPEC section 4):
OPEN -> ACKNOWLEDGED -> RESOLVED, forward-only.One line of the monthly incident index (
incidents/index/YYYY-MM.jsonl).One entry of an
Incident's handling history (SPEC item 11): a status transition
({status, by, at, comment}) or a plain comment (recorded against the incident's
status at the time, without changing it).Records item lifecycle events (SPEC item 9): CREATE, DELETE, RENAME and MOVE, with the acting
user, the
BatchClock timestamp and — when the
actor holds an active matching grant — the grant id.security-13 S-13-09, D-80: the identity of an item's directory, recorded with an activation state
so that a state left behind by a deleted item is not taken for a new item of the same name.
The kind of the item a permission window names (D-71): the item's
TopLevelItemDescriptor
id, display name and icon, recorded when the request is created and copied to the grant at
approval.The activation request form at
<item>/batch-control-activation/ (SPEC item 6a, D-39,
D-64) for a job (JobRequestActionFactory) or a computed folder, which carries the
activation of its children (D-46c, ComputedFolderActivationActionFactory).The job-page Batch Control notice area: whether a run-controlled job is activated, not
activated or on hold, with a link to the activation request form (SPEC item 6a), and, on an
approval-required job, that manual runs need an approved run request, with a link to the
request form (SPEC item 6, e2e-03 DEF-01).
Sidebar entry "Request Change Permission" on a job, linking to the grant request screen with
this job already filled in (U-01).
The job page notices (trigger lock, approval, activation) as a card of core's new job
page.
Contributes the card to a job's widgets on the new job page only.
Per-job "Request Run" page at
/job/<name>/batch-control/ (attached by
JobRequestActionFactory).Attaches the plugin's two per-job sidebar entries, and the trigger-lock notice, to every job.
The job-page notice for blocked unattended triggers (SPEC item 6).
D-71 (spec-review-S6 M-1): an item kind's icon as markup, for answers that are built in Java
rather than in Jelly (the request form's item check,
FormValidation.okWithMarkup).The shipped e-mail
BatchControlNotifier (SPEC item 13, D-36).Generated localization support class.
D-59: the answer to a move that
MoveGuard refused, in the D-48 style: HTTP 403 and a
plain message saying what the move needs and what the user is missing.Immutable description of one notification (SPEC item 13, D-36), handed to every
BatchControlNotifier.Hands request events to every
BatchControlNotifier on a background thread (D-36).The request events a
BatchControlNotifier receives (SPEC item 13, D-36).Paging arithmetic shared by every list screen (D-44).
D-72: the one place where typed
ParameterValues become the masked text that Batch
Control displays or writes (the request's parameters map, run records, incidents, CSV).D-72: disposal of the temporary files that typed parameter values keep until a build takes
them over, for values that will never reach the queue: a run request that ended without a run
(REJECTED, CANCELLED, EXPIRED, INVALIDATED before it was queued), a submission that was refused
before a request was stored, a person's own build submission that the queue gate refused, or
rerun values that could not be completed.
The single place where job full names are turned into store file names and where store file
names are validated.
How many PENDING requests of one kind concern a viewer (D-61): the requests awaiting
their decision as a designated approver holding
BatchControl/Approve, and their own
requests on which they are not a designated approver.The time range of a page query (security-10 S-03): only records inside it count toward the
query's record cap.
Resolves a record id that arrives as a URL segment (
/batch-control/requests/<id>/ and the
other detail URLs) or is about to become a link to one (S-39-01).One page of a bounded record query: the rows to render plus what the pager needs.
Reads the values of a repeated form field (one value per entry, in submission order) from
an
application/x-www-form-urlencoded or a multipart/form-data body alike.D-58c: the runs of an item that were replayed under a permission window, for the two review
surfaces (the batch-control-strategy monitor and the job's Batch Control page).
One marked run: its id and its root-relative build URL, or
null for plain text.D-58c: the hidden marker of a run started by a Replay, Pipeline Rebuild or Restart from Stage
that a user whose permission for it came only from a grant submitted.
D-58c: when a run marked
ReplayUnderGrantAction starts, a REPLAY_UNDER_GRANT
change record names the user, the run and the grant, and the run is added to the marked runs
the review surfaces list.D-72, D-74 (2): the size cap on a run request submission.
D-38a: whether the requester of a run request (not the viewer) lacks
Item/Build
on the request's job, for the request detail page.D-21: renaming or moving a job ends every PENDING/APPROVED request that targets its old
full name in status INVALIDATED (the approver reviewed a different identity than the one
that would run).
One run request at
/batch-control/requests/<id>/: detail view plus the four
state-changing POST endpoints (approve, reject, cancel,
changeApprover).One row of the recent-run table.
D-60: carrying the values of a refused build submission into the job's Request Run form.
Relabels core's "Build Now" sidebar entry on approval-protected jobs (SPEC item 6: the manual
build entry point must not read "Build Now" while run control is on).
D-38b: where
BatchControl/Request is checked for a job-specific use (viewing, cancelling
or re-designating a run or activation request, requesting an activation or hold): the request's
item, so Request assigned on that job or a folder above it counts; Jenkins when the item no
longer exists.The run request lists at
/batch-control/requests/ (D-66): pending requests (oldest
first), active ones (approved, run not started) and ended ones (newest first), each in pages of
50 selected with ?pendingPage=N, ?activePage=N and
?endedPage=N.Lifecycle status of a
RunRequest (and, from slice S2 on, a grant request).The few fields of a run request that listings filter and sort on, kept in memory by the
store so a listing reads only the XML files of the rows it renders.
D-72b (4), security-37 S-37-01: a run request refused because what it would keep (its file
contents and the stored text of its other values,
RequestBodyLimit.keptSize(java.util.List<? extends hudson.model.ParameterValue>, java.util.Map<java.lang.String, java.lang.Long>)) is over the
cap RequestBodyLimit.maxRequestBodyBytes().D-72 (SPEC item 11): an incident rerun could not recover every parameter value of the failed
run (a stashed file, which the build clears when it completes; a core file whose copy under
the build directory is gone; a deleted build), so no request was created.
Daily retention cleanup (SPEC item 12): deletes every month bucket older than the configured
retentionMonths — the runs and changes JSONL files, that month's diff patches, and
that month's incidents (index + XMLs) — and records each deleted month as
ChangeRecord(type=RETENTION) identifying the month as YYYY-MM.What one retention pass over the XML entities deleted.
The build-page counterpart of the job-page approval notice (SPEC item 6, e2e re-audit DEF-31):
on every build of a job whose manual runs need an approved run request, the build page says so
and links the run request form for a viewer who may submit it.
Attaches
RunApprovalNoticeAction to the builds of a job whose manual runs need an
approved request (e2e re-audit DEF-31), and to no build while run control is off or the job
needs no approval (S-18-06).Builds root-relative build URLs from stored identifiers, and small display helpers shared by
the dashboard/incident/history views.
Per-month run counters for the history summary, maintained incrementally from the
append-only
runs/YYYY-MM.jsonl bucket: a summary request only reads the bytes appended
since the previous one.Summary of one build execution (SPEC section 3).
Appends a
RunRecord for EVERY completed build — Freestyle, Pipeline and multibranch
children alike (SPEC item 10) — and drives the SPEC item 11 automatics: incident registration
and the successful-rerun resolvedByRunId link.A request to run a specific job with a fixed set of parameters (SPEC section 3).
One approver change entry: (previous set, new set, changed by, at) (SPEC item 3, D-37).
Completes the APPROVED → EXECUTED transition (SPEC section 4): when a build carrying the
approval marker starts, the linked request is marked EXECUTED with the run id
(
jobFullName#number).The single entry point for every
RunRequest state transition (SPEC items 3, 5, 7;
D-20/D-21/D-22/D-23).The typed parameter values of one run request (D-72, D-74), persisted with XStream at
requests/run/<id>.values.xml, next to the request file, as core keeps parameter values
in build.xml: a Secret field is written in Jenkins' encrypted form.D-75 (1), security-39 S-39-04 (SPEC item 8): the name a screen shows for the item of a grant
request or permission window (
tags/scopeItem.jelly).Masks secret material in config XML text BEFORE it is diffed or stored (SPEC item 9:
"unified diff with secrets masked").
The permissions each Batch Control screen requires, in one place (SPEC item 2, hosting
review).
The tabs of the Batch Control page (hosting review 2026-10-02, PR6): one entry per section the
current user may open, in a fixed order.
One tab: a section of
/batch-control/.Tells the saving user that the guard reverted the authorization part of their save (SPEC item 2,
D-48, D-58a, D-58b): the item is guarded because a permission window covers it or it was
changed under one and not yet reviewed, so a widening of its authorization is undone whoever
saves it.
Tells the saving user when the D-35b guard reverted part of their save (SPEC item 2, D-48,
e2e-03 DEF-35).
Keeps the configuration snapshots (the CONFIGURE diff baselines, ARCHITECTURE section 5) in step
with the items when change recording becomes active (SPEC item 9).
Restart durability (SPEC item 4): after every startup, APPROVED requests that never
executed are re-submitted exactly once (idempotent via the consumption ticket and the
restored-queue/existing-build checks in the policy service).
Durable, build-independent plugin store under
$JENKINS_HOME/batch-control/
(layout in docs/ARCHITECTURE.md section 5).D-72b (2), security-35 S-35-03: an entity could not be written (an I/O failure, or content the
XML writer refused).
Copies between a plain supported strategy and its Batch Control subclass (D-35a, D-35d): the
migration action and its reverse.
D-50, D-50a (SPEC item 2, e2e-03 DEF-37, security-21): whether builds on this instance may run
as SYSTEM although change control is on.
Minimal unified-diff generator for config.xml change records (SPEC item 9).
Items whose configuration in memory carries a fail-closed change that could not be saved: the
D-34 lock of a new or moved job (SPEC item 8,
ItemChangeListener.applyActivationLock(hudson.model.Job<?, ?>, java.lang.String, java.lang.String)) or
the removal of an authorization property a grant holder's creation payload carried (SPEC item 2,
D-35c, GrantViolationGuard).Per-object visibility predicates for the request and grant screens (P-09, security review
S-01).
D-74: permission windows follow their item, as matrix-auth's item permissions do.
D-72b (2), security-35 S-35-03: the characters a stored text may contain.