Disabling plugins from CloudBees CI

3 minute read

When a plugin is no longer used in a CloudBees CI environment, it should be removed either from operations center or from the appropriate controller. Removing unused plugins provides a number of benefits, such as reducing memory overhead at boot or runtime, reducing configuration options in the web UI, and removing the potential for future conflicts with new plugin updates. You have two choices when removing plugins; uninstall or disable. For more information on uninstalling plugins see Uninstalling plugins.

Disabling a plugin is useful for temporarily “turning off” a plugin, and allowing it to be enabled again in a few hours/days. Jenkins will continue to recognize that the plugin is installed, but it will not start the plugin, and no extensions contributed from the plugin will be visible.

The fragments contributed from a disabled plugin to configuration files would follow the same fate as in the case of uninstalled plugins.

Disabling plugins

CloudBees CI provides two methods for disabling plugins:

  • The Plugin Manager in the web UI.

  • The Jenkins CLI disable-plugin command.

To disable a plugin using the web UI:

  1. From the operations center or the appropriate controller, select the Manage Jenkins area.

  2. Select Manage Plugins.

  3. Select the Installed tab.

  4. Find the plugin you want to disable.

    They are listed in alphabetical order.
  5. Select the checkbox in the Enabled column to the right of the plugin you want to disable.

    If the plugin is safe to disable and is not a dependency for other plugins, the checkbox in the Enabled column will be selectable.

A systems administrator can also disable a plugin by creating a file on the Jenkins controller, such as: JENKINS_HOME/plugins/PLUGIN_NAME.hpi.disabled.

The configurations created by the disabled plugin function as if the plugin was uninstalled, insofar as they result in warnings on boot but are otherwise ignored.

To disable a plugin using Jenkins CLI:

See the Jenkins CLI tool guide for more information on downloading and configuring the Jenkins CLI tool.
  • Enter the following command:

java -jar jenkins-cli.jar disable-plugin plugin1 plugin2 plugin3 …​ [-quiet (-q)] [-restart (-r)] [-strategy (-s) strategy]

The disable-plugin command disables one or more installed plugins, using short names. You can specify the verbosity level, how dependencies should be handled, and whether Jenkins should restart after the operation completes.

java -jar jenkins-cli.jar disable-plugin plugin1 plugin2 plugin3 ... [-quiet (-q)] [-restart (-r)] [-strategy (-s) strategy]

Arguments

Argument

Description

plugin1 plugin2 plugin3

The list of plugins to be disabled, specified as the plugin short name.

-quiet (-q)

Be quiet, and print only error messages to the console.

-restart (-r)

Restart Jenkins after disabling plugins.

-strategy (-s) strategy

Specify handling for plugin dependencies:

* none (default) If a mandatory dependent plugin exists and is enabled, do not disable the parent plugin.

* mandatory Disable all mandatory dependent plugins, but do not disable optional dependent plugins.

* all Disable all dependent plugins regardless of whether the dependency is mandatory or optional.

The disable-plugin command was added to Jenkins in v2.151.

Disabling a plugin when Jenkins is down

Occasionally a plugin might prevent Jenkins from restarting, for instance if a dependency has been removed, etc. You can disable a plugin when Jenkins is down so that you can restart Jenkins.

To disable a plugin via File System, create a file, <PLUGIN_ID>.jpi.disabled, inside the $JENKINS_HOME/plugins folder.

For example, the following command will disable the Green Balls plugin:

touch $JENKINS_HOME/plugins/greenballs.jpi.disabled