README.md

Jenkins Timeline (TL) Plugin

Overview

Jenkins TL is a Jenkins plugin that allows users to gain knowledge about the execution of their pipeline builds.

Motivation

Using the Jenkins timeline plugin we are able to identify sequential and parallel steps in a pipeline. This plugins gives us awareness and intuition about how long each step takes as well as what steps would have the most impact if optimized.

Installation

Manual build

Make sure that you follow the development setup and building steps before you attempt building your own plugin package.

• Clone the repository and use make build_all to build the plugin hpi package.
• After a successful build, the packaged file is available in target/jenkins-timeline.hpi.
• In Jenkins, head to Manage Jenkins > Manage Plugins and use the Upload Plugin functionality available under the Advanced tab.
• You might be prompted to restart Jenkins after installing the plugin.

Using the JenkinsCI repository

Available soon!

Usage

The plugin adds a Build Timeline link in every Pipeline build page menu. Clicking it will open up the build timeline in a new tab.

The timeline can be opened during a build for an incremental breakdown of the job or after a build is completed for an overview of old jobs.

Contributing

Helpful resources

If you want to know more about the structure of Jenkins plugins and the Java-side of their development, you can peruse the Jenkins Wiki and the Jenkins Core API reference. You might find the API reference especially useful if you want to tinker with the Java portion of the plugin.

The web application is a standard React app. The Getting started guide for React is a great way to get up to speed with the framework.

Setting up a development environment

To work on the project, you will need ...

• Maven 3.1.0+;
• A Java development environment (JDK 8);
• A local instance of Jenkins;
• npm;

You can either install all of these on your machine, or use the Docker-based shortcuts included in the Makefile.

Docker-based development environment

You can leverage the power of Docker to avoid having to set up the development environment on your machine:

Any of the following can be used by typing make <cmd> given you have Docker installed:

Command	Definition
start_jenkins	Starts a Jenkins docker machine bound to port 8080. Terminates any previous instance of itself.
stop_jenkins	Stops a running instance of the Jenkins docker machine.
clean_jenkins	Removes an existing instance of the Jenkins docker machine.
start_env	Starts a docker machine set up with a copy of the local plugin files and Maven.
stop_env	Stops a runnign instance of the build environment docker machine.
clean_env	Removes an existing instance of the build environment.
exec_env	Gives you console access to the build environment docker machine.
build_and_export	Builds the plugin package from the local files in the build environment and exports the hpi artifact to your local work directory.

Compatibility note

The linked version of Java (JDK 8) is the preferred version for this project, as Maven seems to have trouble building with other versions.

Jenkins setup

When installing Jenkins, make sure to allow the installer to add the recommended plugins to Jenkins. This project depends on the pipeline plugin, installed by default as part of the recommended package.

Building

The makefile is set up with a few useful commands to abstract away mvn calls. Call make build_all to build the hpi file that you can import in your Jenkins instance to install the plugin.

You can find a sample Jenkinsfile under /devResources if you need a sample pipeline to visualize or start from.

Working on the web app

The Node application that is run by the plugin can be worked on without having to rebuild and reinstall the plugin in Jenkins.

To run the web app independently of the rest of the plugin, deactivate your Jenkins instance's security (Manage Jenkins > Configure Global Security, untick the Enable security checkbox and apply/save the changes) and alter the web app code as follows:

//In webapp_src/src/index.js
const buildUrl = [hardcoded build URL taken from Jenkins]

//In webapp_src/src/components/Dashboard.js
...
getStageInfo = stageEndpoint => {
        stageEndpoint = [Jenkins base URL] + stageEndpoint
        return axios.get(stageEndpoint)
        ...
...

These two changes will ensure that the API requests to Jenkins' Workflow API will reach the endpoints properly. Disabling the security will avoid the web app hitting Jenkins' CORS protection.

Make sure to revert those two changes before opening up a PR or building the plugin.

From within the webapp_src directory, you can use the scripts defined in packages.json: npm run start and npm run test to start the application and run the test suites, respectively.

Releasing a new version

Before you can release, you will need to have write access on the Jenkinsci repo

To release, clone the jenkinsci fork locally and set up Maven according to the documentation (see the section about settings.xml and settings-security.xml.

When you are all set up, just run make publish to start the process.

Common errors

java.nio.file.NoSuchFileException during builds

If a java.nio.file.NoSuchFileException about hudson.Extension prevents building using make build, make sure that you have set up your JAVA_HOME properly.

In ~/.bash_profile, make sure to export it as:

export JAVA_HOME=`/usr/libexec/java_home -v 1.8`

Contributors

Thanks goes to these wonderful people emoji key:

Marc Cataford 💻 📖 🚇 📦	sjoanes 🤔 💻	Brandon Baksh 📖	Jake Bolam 📖 🚇	Siavash Mahmoudian 🚇	Shouvik DCosta 📖	jenkins-timeline-bot 🚇
Martin Ringehahn 💬	vuphuong245 📖	Matthew Brunton 💻	Kimi Li 💻

We welcome contributions from the community, Top Hatters and non-Top Hatters alike. Check out our contributing guidelines for more details.

Credits

Thanks to Carol Skelly for donating the github organization!