Folders Plus plugin

Folders Plus provides additional capabilities not available in open source Folders, including the ability to:

  • restrict the use of agents to specific folders

  • move jobs (or subfolders) from one folder to another (or to or from the root of Jenkins)

  • get additional health reports for jobs within a folder

  • set custom icons on a folder

  • define environment variables that will be passed to the builds of all jobs within a folder

  • display selected jobs from subfolders in a higher-level view

  • restrict which kinds of items may be created in a folder

Controlled agents

Folders Plus controlled agents can restrict the jobs that may execute on an agent.

By default, jobs may be assigned to any labeled agent. This can be a problem when specific agents contain secrets or are intentionally task-specific.

Consider the case of a Jenkins instance shared by an operations group and multiple developer groups. The operations group has specific credentials and tools that deploy the company website into production. The operations group has configured a dedicated agent with those credentials and tools. The agent is configured to only accept jobs assigned to that specific agent. However, without Folders Plus, a developer could configure a job to run on the operations agent and copy the credentials or the tools.

Folders Plus controlled agents allow the operations group to limit their task-specific agent to jobs from specific folders.

Configuring controlled agents

The first step is to configure the agent to only accept jobs from within approved folders. Agents configured to only accept jobs from within approved folders will refuse to build jobs outside those folders.

Open the configure screen of the agent (Enabling approved folders functionality on an agent) and select the Only accept builds from approved folders option.

Enabling approved folders functionality on an agent

enable approved folders

After saving the configuration you should see a screen like that in An agent with approved folders functionality enabled and no approved folders assigned

An agent with approved folders functionality enabled and no approved folders assigned

approved folders enabled

At this point the person with permissions to configure the folder needs to create a request for a controlled agent. They need to open the folder in Jenkins (Creating a controlled agent request - step 1) and select the Controlled Slaves action.

Creating a controlled agent request - step 1

approving a folder step 1

This will display the list of controlled agents assigned to the folder (Creating a controlled agent request - step 2). We want to add a new controlled agent so select the Create request action. Confirm the request creation (Creating a controlled agent request - step 3) and the Request Key should be generated and displayed (Creating a controlled agent request - step 4). The request key needs to be given to the person with permissions to configure the controlled agent.

Creating a controlled agent request - step 2

approving a folder step 2

Creating a controlled agent request - step 3

approving a folder step 3

Creating a controlled agent request - step 4

approving a folder step 4

At this point the person with permissions to configure the agent needs to approve the request. They need to select the Approved Folders action from the agent (An agent’s approved folders screen) and select the Controlled Slaves action.

An agent’s approved folders screen

approving a folder step 5

The Approved Folders screen allows for multiple tokens to be issued, a token can be used to sign multiple requests, and it is left to the administrator of the agent to decide whether they want to create a new token or use an existing token.

Creating a new token for each agent has the advantage that each approved folder can be revoked individually. Conversely, re-using an existing token allows for bulk revocation of folders.

If there are no existing tokens for approving controlled agent requests you will need to create a new token by selecting the Create token action and confirming the creation (Creating a token for approving requests) otherwise the authorize button on any existing token can be used to authorize a request using that token. Either route should display the Authorize Request screen (Approving a controlled agent request).

Creating a token for approving requests

approving a folder step 6

Approving a controlled agent request

approving a folder step 7

Enter the Request Key and press the Authorize button. The Request Secret should be generated and displayed (An approved request for a controlled agent). The request key needs to be given to the person with permissions to configure the folder.

An approved request for a controlled agent

approving a folder step 8

At this point the person with permissions to configure the folder needs to return to the request screen and enter the Request Secret provided by the person responsible for configuring the agent. (Completing a controlled agent request) and click the Authorize button.

Completing a controlled agent request

approving a folder step 9

Once the controlled agent request has been completed, the controlled agent should appear in the list of agents (A folder with an approved agent) and the folder should appear on the agent (An agent with an approved folder)

If the person viewing the agent does not have permissions to view the folder, they will not see the folder name when viewing the agent’s status screen or list of approved folders. In this case an additional indicator will be provided detailing the number of "hidden" folders in addition to those that the user is permitted to see.

A folder with an approved agent

folder with controlled slave

An agent with an approved folder

slave with approved folder

Troubleshooting

Issues with third-party plugins

In order to enforce that only jobs belonging to approved folders can be built on a controlled agent it is necessary to identify the job that owns any build submitted to the build queue of Jenkins. Once the job has been identified, the folder hierarchy can be traversed to see if any parent folder is on the list of approved folders.

Once of the extension points that Jenkins provides is the ability to define custom build types that can be submitted to the build queue. When a plugin author is developing such a plugin, they should ensure that the owning build type hierarchy eventually resolves to the build job to which the task belongs whenever a custom build type is associated with a build job.

In the event that a third-party plugin author has not correctly ensured that their custom build type is correctly associated with its originating job, the controlled agents functionality will be unable to identify the originating job, and consequently will refuse to let the job build on the controlled agent.

If it is critical to enable the third-party plugin to build on the agent, and the administrator accepts the risk of allowing other custom build types to run on the controlled agent, there is an advanced option that can be enabled on a per-agent basis.

Issues with builds being blocked forever

There are multiple reasons why Jenkins can block a build from executing. The controlled agent functionality adds an additional reason, however, it should be noted that when Jenkins evaluates a job for building, once it has identified a reason why the job cannot be started, it does not evaluate any of the other reasons. Therefore when Jenkins reports the reason as to why the build is blocked, it will only report the first reason it encountered. In such cases, the user may not realize that the reason for the build being blocked is because it is not within an approved folder.

Jenkins does not re-evaluate whether builds are still blocked until an event causes a probability of jobs being executed. Such events include, but are not limited to

  • A job being added to the build queue

  • A job being removed from the build queue

  • A job completing execution

  • A node coming on-line

  • A node going off-line

If a job is submitted to the build queue and is blocked because it is not in an approved folder, it will not be re-considered for execution until one of the re-evaluation triggers occurs. Therefore, even if the folder containing the job is added to the list of approved folders, existing blocked builds will not become unblocked until a queue re-evaluation trigger is fired.

Other features

There are other smaller features available in Folders Plus.

Moving

You can use the Move action to move a job, or entire subfolder, from one location to another. The configuration, build records, and so on will be physically relocated on disk.

Beware that many kinds of configuration in Jenkins refer to jobs by their relative or full path. If you move a job to a different folder, you may also need to update configuration that was referring to that job.

Health reports

The base Folders plugin has a simple way of displaying a health report next to a folder in the dashboard: it simply indicates the worst status (such as failing) of any job in the folder. Folders Plus offers some alternate metrics:

  • the average health of jobs within the folder

  • whether some jobs are disabled

  • counts of jobs with different statuses, such as stable or unstable

Icons

Normally folders all have a fixed "folder" icon. Folders Plus allows you to customize this with other kinds of icons:

  • a blue, yellow, or red ball corresponding to the most broken job in the folder

  • a variety of icons packaged with Jenkins, such as that for a "package"

  • any icon you like, if you provide a URL

Environment variables

You may configure an Environment variables property on a folder giving a list of variable names and values. These will be accessible as environment variables during builds. This is a good way to define common configuration to be used by a lot of jobs, such as SCM repository locations.

Newer versions of Jenkins also allow these variables to be used during SCM polling or other contexts outside of builds.

List view column

The Pull information from nested job list view column may be selected when configuring a view on a folder or at top level in Jenkins. This column allows you to display some aspect of a job (available as another kind of list view column) for every subfolder being displayed.

For example, you might have a dozen folders corresponding to different products, each containing several jobs with predictable names: build, release, and so on. You can create a view at the Jenkins root which contains all these folders as entries. Then add this kind of list view column, specifying the job name build and the standard Status list view column. Now your custom view will display all of the product folders, and for each will show a blue, yellow, or red ball corresponding to the current status of the build job in that folder.

Restricting children

The Folders Plus plugin allows you to specify the types of jobs that a particular folder allows. To choose the specific job types that the folder can allow, enable Restrict the kind of children in this folder as shown in Specifying parameter types for Folders.

Specifying parameter types for Folders

folder options