Folders Plus plugin

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.

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.

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.

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

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.

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.

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:

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

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 Manage Jenkins → Configure System → Environment variables), but Folder environment variables will override any parent Folder environment variables.

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.

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.