Themes for user interface

It is possible to customize Jenkins' appearance with custom themes. This feature is not a part of the Jenkins core, but it is supported through plugins. These are the 2 most popular plugins:

Simple Theme Plugin - allows customizing the Jenkins UI by providing custom CSS and Javascript files. It also supports replacing the Favicon. There are many themes created by Jenkins users.
Login Theme Plugin - allows modifying or replacing the Jenkins login screen. It is required to customize login screens starting from Jenkins 2.128 (announcement).

Using themes

To configure a theme, you need to first install a theme management plugin and then configure it. Both plugins can be managed in the Jenkins Web UI or by the Configuration-as-Code Plugin. See the plugin documentation for the detailed usage guidelines.

Example for the Jenkins Neo2 theme:

Themes support policy

Jenkins themes are provided “as is”, without warranty of any kind, implicit or explicit. The Jenkins core, plugins and other component updates may break theme compatibility without notice.

At the moment, the Jenkins project does not provide specification for layouts/CSS, and we cannot guarantee backward or forward compatibility. We try to reflect major changes in changelogs (e.g. see the ‘developer’ changes in the Jenkins changelog), but minor changes may not be included there.

Why?

There is an ongoing effort focused on improving Jenkins look-and-feel, accessibility, and user experience. This area is mission-critical to the project. Currently, the Jenkins user interface (UI) is widely considered dated, and we want to change this perception. There are multiple initiatives in the Jenkins Roadmap being coordinated by the Jenkins User Experience SIG.

Major UI changes imply incompatible changes in layouts and the CSS structure which is critical for theme plugins. Historically Jenkins had no explicit support policy for themes, and we do not want to provide compatibility requirements which would create obstacles for reworking the main Jenkins interface. Later, once the Jenkins UI rework reaches its destination and the UI becomes more stable, we could consider creating specifications for theme extensibility so that we could make themes more stable and maintain compatibility.

Reporting and fixing issues

Users are welcome to report discovered compatibility issues to theme maintainers, and to submit patches there. It is possible to just fix a theme locally, but other theme users would appreciate compatibility fixes in upstream repositories.

We will generally reject bug reports to the Jenkins core/plugins involving broken UI elements with a custom theme. We will consider pull requests which restore compatibility and do not block further Web UI evolvement.

If a theme outside the jenkinsci GitHub organization is no longer maintained, it is fine to fork it and to create a new version. For themes hosted within the jenkinsci organization, we have an adoption process which also applies to themes.

Information for theme developers

We encourage Jenkins users to create themes and to share them. Such themes could be a great way to experiment with UI enhancements, and we would be happy to consider enhancements from them for a default Jenkins theme.

To improve the user experience, please consider the following recommendations:

Explicitly document compatibility for themes.
- Compatibility documentation should include: required theme plugins and versions, target Jenkins core version, plugin requirements and versions if applicable (UI/CSS are overridden), and browser compatibility.
- Examples of such documentation: Jenkins Atlassian Theme, Neo2
Version themes with tags on Git and to maintain changelogs with explicit references to changes in the supported versions (e.g. see our release drafter documentation as one of the ways to automate changelogs).
Explicitly define an OSI-approved open source license so that users can freely modify and redistribute them.
- This is also a prerequisite for hosting themes in Jenkins GitHub organizations and, in the future, theme marketplaces or other similar promotion engines.

If you would like to share a story about Jenkins themes, please let the Advocacy&Outreach SIG know!

User Handbook

Tutorials

Resources