Table of contents

Plugin management


Folders Plus Plugin

Introduction

The Folders Plus plugin provides additional capabilities not available in the free Folders plugin, including the ability to:

  • restrict the use of build 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 build agents

Core Jenkins functionality does not provide any mechanism to prevent somebody who can configure a build from assigning that build to a build agent. This can be a concern when specific build agents contain secrets that are not for general consumption.

Consider the case of a Jenkins instance shared by both an Operations group and multiple Developer Groups. The operations group have specific credentials that are required in order to deploy the company website into production, so the operations group create a dedicated build agent specifically for deploying the company website into production and store the required credentials directly on that build agent. The build agent is configured to only accept jobs that are tied to the specific build agent. However there is nothing stopping a developer from configuring a job they control to run on the operations build agent and copy off the credentials.

The Controlled Build Agents functionality added by the Folders Plus plugin provides the required restrictions to prevent the above concern.

Note

The controlled build agents functionality is designed to allow the management of controlled build agents in a situation where the person responsible for the build agent does not have permissions to configure the folder that will be approved to use the build agent and that the person responsible for the folder does not have permissions to configure the build agent.

Future versions of this plugin may provide a simplified pipeline for the case where the person setting up the controlled build agent has the configure permissions on both the build agent and the folder.

Configuring controlled build agents

The first step is to configure the build agent to only accept jobs from within approved folders.

Note

Once a build agent is configured to only accept jobs from within approved folders it will refuse to build jobs in the root of Jenkins.

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

enable approved folders
Figure 1. Enabling approved folders functionality on a build agent

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

approved folders enabled
Figure 2. A build agent with approved folders functionality enabled and no approved folders assigned

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

approving a folder step 1
Figure 3. Creating a controlled build agent request - step 1

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

approving a folder step 2
Figure 4. Creating a controlled build agent request - step 2
approving a folder step 3
Figure 5. Creating a controlled build agent request - step 3
approving a folder step 4
Figure 6. Creating a controlled build agent request - step 4

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

approving a folder step 5
Figure 7. A build agent’s approved folders screen
Note

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

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

If there are no existing tokens for approving controlled build 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 build agent request).

approving a folder step 6
Figure 8. Creating a token for approving requests
approving a folder step 7
Figure 9. Approving a controlled build agent request

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

approving a folder step 8
Figure 10. An approved request for a controlled build agent

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 build agent. (Completing a controlled build agent request) and click the Authorize button.

approving a folder step 9
Figure 11. Completing a controlled build agent request

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

Note

If the person viewing the build agent does not have permissions to view the folder, they will not see the folder name when viewing the build 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.

folder with controlled slave
Figure 12. A folder with an approved build agent
slave with approved folder
Figure 13. A build agent with an 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 build 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 build agents functionality will be unable to identify the originating job, and consequently will refuse to let the job build on the controlled build agent.

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

Issues with builds being blocked forever

There are multiple reasons why Jenkins can block a build from executing. The controlled build 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.

Miscellaneous 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.

folder options
Figure 14. Specifying parameter types for Folders