Guardrails / jenkins

Pipelines declare a timeout

jenkins/job-timeout-set@v1

Every declarative pipeline declares how long it may run, on the pipeline itself or on every stage, so a hung build is cut off rather than holding an executor.

Id	jenkins/job-timeout-set
Version	v1
Category	jenkins
Default severity	info
Interpreter	python3
Timeout	30 seconds
Violations tolerated	0
Collects	jenkins

Collectors

This guardrail gathers nothing itself. It depends on the collectors below, which the CLI runs once per build before any check, and reads what they found out of GUARDRAIL_FACTS. A collector that collects nothing skips this guardrail rather than failing it.

Collector	Gathers	Inputs it is given
jenkins	The Jenkinsfiles the repository carries, read in Jenkins's own vocabulary: whether each is a declarative pipeline or a scripted one, the agent it asks for, the stages in the order they are declared with the steps inside them, the timeouts its options blocks declare, the shared libraries it loads and how tightly each is pinned, and the credential ids it reaches for. A Jenkinsfile is Groovy rather than a declaration, so it is read by pattern and scanned says so. Names and ids only, never a credential, an environment value or a parameter value.	jenkinsfiles

The inputs above are this guardrail's own, passed straight through. Configuring one in buildnote.json changes what is collected, and two guardrails configured the same way share the one collection.

Configuration

{
  "guardrails": {
      "failOn": "error",
      "comment": true,
      "checks": [
          {
              "use": "jenkins/job-timeout-set@v1",
              "severity": "info",
              "with": {
                  "jenkinsfiles": "Jenkinsfile,Jenkinsfile.*,*.Jenkinsfile",
                  "maxMinutes": "60"
              },
              "exemptions": []
          }
      ]
  }
}

Inputs

Input	Description	Default	Environment variable
jenkinsfiles	Comma separated globs naming the Jenkinsfiles to read.	Jenkinsfile,Jenkinsfile.*,*.Jenkinsfile	GUARDRAIL_INPUT_JENKINSFILES
maxMinutes	Longest timeout accepted. A stage declaring more than this is treated as declaring none.	60	GUARDRAIL_INPUT_MAXMINUTES

How to fix

Declare one on the pipeline, where it covers every stage:

pipeline {
  options {
    timeout(time: 30, unit: 'MINUTES')
  }
}

Jenkins sets no timeout of its own. A build that hangs holds its executor until somebody notices and aborts it by hand, and on a controller with a handful of executors that is the whole queue stopped behind one stuck stage. An options block on a stage covers that stage and every stage nested inside it, so either the pipeline declares a timeout or each of its stages does.

A scripted pipeline is skipped rather than reported: a timeout there is a step in ordinary Groovy, so its absence from what could be read is not proof it is not there.

More in jenkins

• jenkins/shared-library-pinned. Every @Library annotation and library step names a tag or a commit sha rather than a branch, so the library code a build runs cannot change underneath it.

All 2 jenkins guardrails