Package io.jenkins.plugins.batchcontrol.ops

Class IncidentService

java.lang.Object
io.jenkins.plugins.batchcontrol.ops.IncidentService
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public final class IncidentService extends Object
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. No other class may change an incident's status.

Every load→validate→mutate→persist sequence runs under one ReentrantLock, so concurrent transitions serialize and the loser is refused on the already-changed status.

Failure families follow RunRequestService: IllegalArgumentException for bad input (unknown id, blank comment where required), IllegalStateException for refused transitions.

  • Method Details

    • get

      public static IncidentService get()

    • load

      public Incident load(String id)
      Loads an incident by id, or null.

    • list

      public List<Incident> list(YearMonth month)
      Every incident created in the given month, in creation order.

    • openForRun

      public Incident openForRun(Run<?,?> run)
      Opens an incident for a completed build whose result is in the configured incidentResults — regardless of what caused the build (SPEC item 11, D-10). Called by the run listener; returns null when the result is outside the configured set.

      D-19: the stored logTail masks the build's sensitive parameter values and encrypted Secret payloads; other secrets echoed to the console are a documented detection limit. The stored parameters mask sensitive values entirely.

    • acknowledge

      public Incident acknowledge(String id, String comment)
      OPEN -> ACKNOWLEDGED; any other current status is refused (forward-only). R1-01: a comment holding a character XML 1.0 cannot store is refused (IllegalArgumentException) before anything changes.

    • resolve

      public Incident resolve(String id, String comment)
      ACKNOWLEDGED -> RESOLVED only (SPEC section 4: OPEN must pass ACKNOWLEDGED first). R1-01: the comment is checked as for acknowledge(java.lang.String, java.lang.String).

    • addComment

      public Incident addComment(String id, String comment)
      Appends a comment to the incident history without changing the status — allowed in every status, RESOLVED included (SPEC section 4). The entry is recorded against the incident's current status. R1-01: the comment is checked as for acknowledge(java.lang.String, java.lang.String).

    • rerun

      public RunRequest rerun(String incidentId, String approver)
      Creates a rerun RunRequest carrying the failed run's own parameter values (D-72: taken from the build's ParametersAction, original secrets and recoverable file values included) and links it both ways: request.incidentId and incident.rerunRequestIds. The caller becomes the requester; permission and approver checks are those of RunRequestService.create(hudson.model.Job<?, ?>, java.util.List<hudson.model.ParameterValue>, java.lang.String, java.lang.String).
      Throws:
      RerunNeedsFormException - when a value of the failed run cannot be recovered (a stashed file, a core file whose copy under the build is gone, a deleted build); no request is created and the rerun continues on the job's Request Run form

    • canRerun

      public boolean canRerun(Incident incident)
      Whether the current user could request a rerun of incident (e2e-03 DEF-12): the incident's job still exists and RunRequestService.canRequest(hudson.model.Job<?, ?>) holds for it, which is what rerun(java.lang.String, java.lang.String) and the request creation check. Screens show the rerun form only then.

    • rerun

      public RunRequest rerun(String incidentId, List<String> approvers)
      Approver-set form (D-37) of rerun(String, String).

    • linkableIncident

      @CheckForNull public String linkableIncident(@CheckForNull String incidentId, @CheckForNull Job<?,?> job)
      D-72a (SPEC item 11): the incident a run request submitted from the Request Run form may be linked to, when an incident rerun fell back to that form and the form carried the incident id back. Returns the stored incident's id only when all of these hold, else null: The value comes from a form field, so it is never trusted: a bad reference is ignored, never an error, and the answer reveals nothing a rerun would not. The caller passes the result to RunRequestService.create(Job, List, String, List, String), which links the request to the incident so a successful run records resolvedByRunId. Read only.

    • requireRerunTarget

      public Incident requireRerunTarget(String incidentId, Job<?,?> job)
      The incident a run request for job is linked to (SPEC item 11): it must exist and belong to job. Called by request creation before anything is stored.
      Throws:
      IllegalArgumentException - when there is no such incident of that job

    • recordRerunRequest

      public void recordRerunRequest(String incidentId, String requestId)
      Lists the stored run request requestId among the incident's rerun requests (the link back from the incident; the request itself carries incidentId). Called by request creation once the request is stored, outside the request service's lock; adding the same id again changes nothing. Never throws: the request is already stored and its incidentId alone drives resolvedByRunId, so a failure is only logged.

    • linkResolvedBy

      public void linkResolvedBy(String incidentId, String runId)
      Records the successful linked rerun on the incident (SPEC item 11): sets resolvedByRunId but never touches the status — resolution stays a human decision. Called by the run listener when a request-linked build ends SUCCESS.

    • maskedParameters

      public static Map<String,String> maskedParameters(Run<?,?> run)
      The build's parameters in their masked display form (ParameterDisplay, D-72): a sensitive value is the mask, a file value [file] <original file name>. The plaintext of a sensitive value never leaves this method.