The Folders Plus plugin 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 and select the
Only accept builds from approved folders
option.
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 and select the Controlled Agents
action.
This will display the list of controlled agents assigned to the folder. We want to add a new controlled agent so select the
Create request
action. Confirm the request creation and the
Request Key
should be generated and displayed. The request key
needs to be given to the person with permissions to configure the
controlled agent.
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 and select the Controlled Agents
action.
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 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.
Enter the Request Key
and press the Authorize
button. The
Request Secret
should be generated and displayed. The request key
needs to be given to the person with permissions to configure the
folder.
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 and click the
Authorize
button.
Once the controlled agent request has been completed, the controlled agent should appear in the list of agents and the folder should appear on the agent.
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. |
Troubleshooting
Issues with third-party plugins
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. It 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 that 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 jobs and folders
-
Health reports for entire folders
-
Icons for status reports and other
-
Environment variables for all jobs in the folder
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 the configuration 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.
Note: Folder environment variables will not override global environment variables (set at
), but Folder environment variables will override any parent Folder environment variables.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 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. For example, let’s make Pipeline the job type available and then add a new one.
-
Navigate to your Jenkins dashboard.
-
Select New Item to create a new folder called
FolderSample
.-
Select Folder as the item type.
-
Select OK. The Configure screen displays.
-
Select Restrict the kind of children in this folder.
-
Select the Pipeline option.
-
Select Save and return to the main dashboard.
Figure 1. Restrict the kind of children in this folder - Pipeline option
-
-
Select New Item to create a new folder template called
TeamFolder
.-
Select Folder Template as the item type.
-
Select OK. The Configure screen displays.
-
Enter the following in the Description field:
Create a Folder with restricted job types list
. -
Configure remaining fields to your specific needs.
-
Select Save and return to the main dashboard.
-
-
-
Select
FolderSample
configure from list.-
Select Restrict the kind of children in this folder.
-
Select the TeamFolder option.
-
Select Save and return to the main dashboard.
Figure 2. Restrict the kind of children in this folder - TeamFolder option
-
-
Select
TeamFolder
configure from list.-
Scroll down to the Transformer section.
-
Under Load Prototype, enter
FolderSample
in the Job field. -
Select Load.
-
Select Save and return to the main dashboard.
-
-
-
Select FolderSample from the list.
-
Select Create a job, the New Item screen displays.
-
Enter
TeamARootFolder
as the item name. -
Select the Team Folder option for the item type.
-
Select OK.
Figure 3. New Item - TeamARootFolderAn error message may appear requesting the Transformer script be approved. Navigate back to the previous Configure page and select the Approve script button in the Transformer section.
-
Return to FolderSample page.
-
Repeat Create a job steps.
-
Select Save on the new folder page displayed.
-
-
Continue creating folders or subfolders as the "TeamFolder" type, this ensures all folders underneath are restricted to the Pipeline and TeamFolder items only.
Figure 4. FolderSample with foldersGroups can also be assigned access to these folders.
For more information, refer to Folders Plugin, Folders Template, or Role-Based Access Control Plugin.