KB at your finger tips
This is one stop global knowledge base where you can learn about all the products, solutions and support features.
Java requirements
There are separate run and job execution requirements for Jenkins installations.
Running Jenkins system
Jenkins requires Java 11 or 17 since Jenkins 2.357 and LTS 2.361.1. Read more about this in the announcement blog post.
|
Upgrading Java version to 11
Upgrading an existing Jenkins setup from Java 8 to Java 11? Refer to the upgrade guidelines. |
Running Jenkins on Java 11 in Docker
Java 11 Docker installation instructions are included in "Downloading and running Jenkins in Docker".
Alternatively, the
jenkins/jenkins:jdk17
Docker image allows you to run the Jenkins controller on Java 17.
All other Java versions are not supported.
These requirements apply to all components of the Jenkins system, including the Jenkins controller, all types of agents, CLI clients, and other components.
The Jenkins project performs a full test flow with the following JDK/JREs:
-
OpenJDK JDK / JRE 11 - 64 bits
-
OpenJDK JDK / JRE 17 - 64 bits
JRE/JDKs from other vendors are supported and may be used. Refer to our issue tracker for known Java compatibility issues.
Running Java-based tools and builds on Jenkins
The version of the JDK used to build Java-based projects, or the version of Java used to run Java-based tools is independent from the version of Java used to run the Jenkins controller and agent processes. During a build, any version of the JRE or JDK can be launched as long as it’s compatible with the system the build is running on. This includes:
-
Execution of
javaorjavacfrom shell build steps and similar -
Execution of Maven/Ant/⦠build steps using a JDK managed by a JDK tool installer
A few plugins have more strict requirements, generally requiring that a build is executing in the same version of Java as is used to run the Jenkins controller and agents. A notable example of that is Maven Integration Plugin, which requires that the version of the JDK used for the Maven build must be at least the same version as is used for the Jenkins controller. These cases are generally documented in the plugin documentation.
Monitoring Java versions
Modern versions of Jenkins controllers and Jenkins agents verify Java requirements and notify users when they are launched with an unsupported version.
The Versions Node Monitors plugin provides detailed Java version monitoring.
Activity View
-
Navigation Bar
- Activity
- Branches
- Pull Requests
The Blue Ocean Activity view shows all activities related to one Pipeline.
|
Blue Ocean status
Blue Ocean will not receive further functionality updates. Blue Ocean will continue to provide easy-to-use Pipeline visualization, but it will not be enhanced further. It will only receive selective updates for significant security issues or functional defects. |
Navigation Bar
The Activity view includes the standard navigation bar at the top and a local navigation bar below it.
The local navigation bar includes:
-
Pipeline Name - Selecting this displays the default Activity tab.
-
Favorites Toggle - Selecting the favorite icon ☆ to the right of the Pipeline name, adds a branch to the favorites list shown on the dashboard’s favorites list.
-
Tabs (Activity, Branches Pull Requests) - Selecting one of these navigates to the corresponding information in the Activity view.
Activity
The default tab of the Activity view shows a list of the latest completed or active runs. Each line represents the status of a run, run ID, commit information, and when the run completed.
-
Selecting a run will bring up the Pipeline run details to provide Pipeline visualization.
-
Active runs can be aborted from this list by selecting the stop icon, which is represented by a ◾ within a circle.
-
Runs that have been completed can be re-run by selecting the re-run icon ↺.
-
The list can be filtered by branch using the "Branch" drop-down in the list header.
This view does not allow runs to be edited or marked as favorites. To perform these actions, select the Branches tab.
Branches
The Branches tab shows a list of all branches that have a completed or active run in the current Pipeline. Each line in the list corresponds to a branch in source control, displaying the overall health of the branch based on the status of the most recent run, branch name, commit information, and when the run completed.
Selecting a branch brings up the Pipeline run details for the latest completed or active run of that branch.
-
Pipelines where the latest run has been completed can be run again by selecting the run icon, represented by a in a circle.
-
Active runs can be aborted, and display a stop icon, which is represented by a ◾ within a circle.
-
-
Selecting the history icon allows you to view the run history for that branch.
-
The edit icon, represented by a , opens the Pipeline editor for that branch.
-
The favorite ☆ icon adds a branch to your favorites list on the dashboard. On the dashboard a branch listed under favorites displays a solid star ★. Deselecting the star removes the branch from the favorites list.
Pull Requests
The Pull Requests tab displays a list of all pull requests for the current Pipeline, that have a completed or active run. Each line in the list corresponds to a pull request in source control, which displays the status of the most recent run, run ID, summary, author, and when the run completed.
Blue Ocean displays pull requests and branches separately, but the lists behave similarly. Selecting a pull request in this list will bring up the Pipeline run details for the latest completed or active run of that pull request.
-
Active runs can be aborted from this list by selecting the stop icon, which is represented by a ◾ within a circle.
-
Pull requests whose latest run has been completed can be run again by selecting the run icon, represented by a in a circle.
The pull request list does not display health icons, and pull requests cannot be edited or marked as favorites.
| By default, when a pull request is closed, Jenkins removes the Pipeline from Jenkins, and runs for that pull request are no longer accessible from Jenkins. The Pipelines removed in this way will need to be cleaned up in the future. This can be changed by adjusting the configuration of the underlying multi-branch Pipeline job. |
Was this page helpful?
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.
Creating a Pipeline
-
Setting up your Pipeline project
-
For a Git repository
- Local repository
- Remote repository
-
For a repository on GitHub
- Create your access token
- Choose your GitHub account/organization and repository
-
For a repository on Bitbucket Cloud
- Choose your Bitbucket account/team and repository
-
For a Git repository
Blue Ocean makes it easy to create a Pipeline project in Jenkins.
You can generate a Pipeline from an existing
Jenkinsfile
in source control, or you can use the Blue Ocean Pipeline editor to create a Pipeline as a
Jenkinsfile
that is committed to source control.
|
Blue Ocean status
Blue Ocean will not receive further functionality updates. Blue Ocean will continue to provide easy-to-use Pipeline visualization, but it will not be enhanced further. It will only receive selective updates for significant security issues or functional defects. Alternative options for Pipeline visualization, such as the Pipeline: Stage View and Pipeline Graph View plugins, are available and offer some of the same functionality. While not complete replacements for Blue Ocean, contributions are encouraged from the community for continued development of these plugins. The Pipeline syntax snippet generator assists users as they define Pipeline steps with their arguments. It is the preferred tool for Jenkins Pipeline creation, as it provides online help for the Pipeline steps available in your Jenkins controller. It uses the plugins installed on your Jenkins controller to generate the Pipeline syntax. Refer to the Pipeline steps reference page for information on all available Pipeline steps. |
Setting up your Pipeline project
To start setting up your Pipeline project in Blue Ocean, select the New Pipeline button at the top-right of the Blue Ocean Dashboard.
If your Jenkins instance is new or has no Pipeline projects or other items configured, Blue Ocean displays a Welcome to Jenkins message that allows you to select the Create a new Pipeline option to start setting up your Pipeline project.
You now have a choice of creating your new Pipeline project from a:
-
Standard Git repository
-
Repository on GitHub or GitHub Enterprise
-
Repository on Bitbucket Cloud or Bitbucket Server
For a Git repository
To create your Pipeline project for a Git repository, click the Git button under Where do you store your code?
In the Connect to a Git repository section, enter the URL for your Git repository in the Repository URL field.
You now must specify a local or remote repository from which to build your Pipeline project.
Local repository
If your URL is a local directory path beginning with a forward slash
/
, such as
/home/cloned-git-repos/my-git-repo.git
, you can proceed to select the
Create Pipeline
option.
Blue Ocean then scans your local repository’s branches for a
Jenkinsfile
, and starts a Pipeline run for each branch containing a
Jenkinsfile
.
If Blue Ocean cannot find a
Jenkinsfile
, you are prompted to create one through the Pipeline editor.
Local repositories are typically limited to file system access and are normally only available from the controller node. Local repositories are also known to require more complicated path names on Windows than most users want to manage. Users are advised to run jobs on agents, rather than running them directly on the controller. Therefore, you should use a remote repository rather than a local repository for the best Blue Ocean experience.
Remote repository
Since the Pipeline editor saves edited Pipelines to Git repositories as `Jenkinsfile`s, Blue Ocean only supports connections to remote Git repositories over the SSH protocol.
If your URL is for a remote Git repository, be sure your URL starts with either:
-
ssh://- which displays asssh://gituser@git-server-url/git-server-repos-group/my-git-repo.git
or -
user@host:path/to/git/repo.git- which displays asgituser@git-server-url:git-server-repos-group/my-git-repo.git
Blue Ocean automatically generates an SSH public/private key pair or provides you with an existing pair for the current Jenkins user. This credential is automatically registered in Jenkins with the following details for this Jenkins user:
-
Domain :
blueocean-private-key-domain -
ID :
jenkins-generated-ssh-key -
Name :
<jenkins-username> (jenkins-generated-ssh-key)
You must ensure that this SSH public/private key pair is registered with your Git server before continuing.
If you have not already done this, follow these two steps.
-
Configure the SSH public key component of this key pair (which you can copy and paste from the Blue Ocean interface) for the remote Git server’s user account (e.g., within the
authorized_keysfile of the machine’sgituser/.sshdirectory).This process allows your Jenkins user to access the repositories that your Git server’s user account has access to. Refer to the "Setting Up the Server" of the Pro Git documentation. -
Return to the Blue Ocean interface.
Select the Create Pipeline option.
Blue Ocean scans your local repository’s branches for a
Jenkinsfile
and starts a Pipeline run for each branch containing a
Jenkinsfile
.
If Blue Ocean does not find a
Jenkinsfile
you are prompted to create one through the Pipeline editor.
For a repository on GitHub
To create your Pipeline project directly for a repository on GitHub, select the GitHub option under Where do you store your code? .
In the
Connect to GitHub
section, enter your GitHub access token into the
Your GitHub access token
field.
If you previously configured Blue Ocean to connect to GitHub using a personal access token, Blue Ocean takes you directly to the
GitHub account/organization and repository choice steps below:
If you do not have a GitHub access token, select the Create an access key here option to open GitHub to the New personal access token page.
Create your access token
-
In the new tab, sign in to your GitHub account. On the New Personal Access Token page, specify a brief Token description for your GitHub access token, such as
Blue Ocean.An access token is usually an alphanumeric string that represents your GitHub account, along with permissions to access various GitHub features and areas through your GitHub account. The new access token process, initiated by selecting Create an access key here , has the appropriate permissions pre-selected that Blue Ocean requires to access and interact with your GitHub account. -
Scroll down to the end of the page, and select Generate token .
-
On the resulting Personal access tokens page, copy your newly generated access token.
-
Back in Blue Ocean, paste the access token into the Your GitHub access token field, and then select Connect .
Your current Jenkins user now has access to your GitHub account and you can now choose your GitHub account/organization and repository. Jenkins registers this credential with the following details for this Jenkins user:
-
Domain :
blueocean-github-domain -
ID :
github -
Name :
<jenkins-username>/****** (GitHub Access Token)
Choose your GitHub account/organization and repository
Blue Ocean prompts you to choose your GitHub account or an organization you are a member of. You are also asked for the repository containing your Pipeline project.
-
In the Which organization does the repository belong to? section, select either:
-
Your GitHub account, to create a Pipeline project for one of your own GitHub repositories or one which you have forked from elsewhere on GitHub.
or -
The organization of which you are a member, to create a Pipeline project for a GitHub repository located within this organization.
-
-
In the Choose a repository section, select the repository within your GitHub account or organization from which to build your Pipeline project.
If your list of repositories is long, you can use the Search option to filter your results.
-
Click Create Pipeline .
Blue Ocean scans your local repository’s branches for a
Jenkinsfile
and starts a Pipeline run for each branch containing a
Jenkinsfile
.
If Blue Ocean does not find a
Jenkinsfile
, you are prompted to create one through the Pipeline editor.
| Under the hood, a Pipeline project created through Blue Ocean is actually a "multibranch Pipeline." Therefore, Jenkins looks for the presence of at least one Jenkinsfile in any branch of your repository. |
For a repository on Bitbucket Cloud
To create your Pipeline project directly for a Git or Mercurial repository on Bitbucket Cloud, select the Bitbucket Cloud button under Where do you store your code?
In the Connect to Bitbucket section, enter your Bitbucket email address and password into the Username and Password fields.
-
If you previously configured Blue Ocean to connect to Bitbucket with your email address and password, Blue Ocean takes you directly to the Bitbucket account/team and repository selection steps below.
-
If you entered these credentials, Jenkins registers them with the following details for this Jenkins user:
-
Domain :
blueocean-bitbucket-cloud-domain -
ID :
bitbucket-cloud -
Name :
+<bitbucket-user@email.address>/ (Bitbucket server credentials)
Select Connect and your current/logged in Jenkins user will now have access to your Bitbucket account. You can now choose your Bitbucket account/team and repository.
Choose your Bitbucket account/team and repository
Blue Ocean prompts you to choose your Bitbucket account or a team you are a member of, as well as the repository containing your project to be built.
-
In the Which team does the repository belong to? section, select either:
-
Your Bitbucket account to create a Pipeline project for one of your own Bitbucket repositories, or one which you have forked from elsewhere on Bitbucket.
-
A team of which you are a member to create a Pipeline project for a Bitbucket repository located within this team.
-
-
In the Choose a repository section, select the repository in your Bitbucket account or team from which to build your Pipeline project.
If your list of repositories is long, you can filter this list using the Search option.
-
Click Create Pipeline .
Blue Ocean scans your local repository’s branches for a
Jenkinsfile
and starts a Pipeline run for each branch containing a
Jenkinsfile
.
If Blue Ocean does not find a
Jenkinsfile
, you are prompted to create one through the Pipeline editor.
| Under the hood, a Pipeline project created through Blue Ocean is actually a "multibranch Pipeline." Therefore, Jenkins looks for the presence of at least one Jenkinsfile in any branch of your repository. |
Was this page helpful?
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.
Dashboard
- Navigation bar
- Pipelines list
-
Favorites list
- Health icons
- Run status
Blue Ocean’s "Dashboard" is the default view when opening Blue Ocean. It disaplays an overview of all Pipeline projects configured on a Jenkins instance.
|
Blue Ocean status
Blue Ocean will not receive further functionality updates. Blue Ocean will continue to provide easy-to-use Pipeline visualization, but it will not be enhanced further. It will only receive selective updates for significant security issues or functional defects. |
The Dashboard consists of a blue navigation bar at the top, the Pipelines list, and the Favorites list.
Navigation bar
The Dashboard includes the blue navigation bar along the top of the interface.
The bar is divided into two sections:
-
A common section along the top.
-
A contextual section below.
-
The contextual section changes depending on the Blue Ocean page you are viewing.
-
When viewing the Dashboard, the navigation bar’s contextual section includes:
-
Search pipelines : This field allows users to filter the Pipelines list to match the text you enter into this field.
-
New Pipeline : This option begins the process of creating a Pipeline.
Pipelines list
The Pipelines list is the Dashboard’s default list. It is the only list displayed the first time Blue Ocean is accessed.
The list shows the overall state of each Pipeline configured in the Jenkins instance. The list can include other items configured in the Jenkins instance. The following information is displayed for each Pipeline listed:
-
The item’s NAME
-
The item’s HEALTH
-
The number of BRANCHES and pull requests (PRs) that are passing or failing within the Pipeline’s source control repository.
-
A ☆, indicating whether or not the item has been manually added to your current Jenkins Favorites list.
Selecting an item’s ☆ will toggle between:
-
Adding the default branch of the item’s repository to your Favorites list, which is indicated by a solid ★.
-
Removing the item’s default branch from this list, which is indicated by an outlined ☆.
Selecting an item in the Pipelines list will display that item’s Activity View.
Favorites list
The Favorites list appears above the Dashboard’s default Pipelines list when at least one Pipeline/item is present in your Favorites list.
This list provides key information and actions for a core subset of your accessible items in the Pipelines list. This key information includes the current run status for an item and its repository’s branch, the name of the branch, the initial part of the commit hash, and the last run time. This list also includes options to run or re-run the item on the indicated branch.
You should only add an item or branch to your Favorites list if it needs regular monitoring. Adding an item’s specific branch to your Favorites list can be done through the item’s Activity View.
Blue Ocean automatically adds branches and PRs to this list when they include a run that contains any modifications you have performed.
You can also manually remove items from your Favorites list by deselecting the solid ★ in this list. When there are no longer items in this list, the list is removed from the Dashboard. Selecting the favorite ★ for any item will bring the list back to your Dashboard.
Selecting an item in the Favorites list opens the Pipeline run details for the latest run on the branch or PR indicated.
Health icons
Blue Ocean represents the overall health of a Pipeline/item or one of its branches using weather icons. These icons change depending on the number of recent builds that have passed.
Health icons on the Dashboard represent overall Pipeline health, whereas the health icons in the Branches tab of the Activity View represent the overall health for each branch.
| Icon | Health |
|---|---|
|
|
Sunny , more than 80% of Runs passing |
|
|
Partially Sunny , 61% to 80% of Runs passing |
|
|
Cloudy , 41% to 60% of Runs passing |
|
|
Raining , 21% to 40% of Runs passing |
|
|
Storm , less than 21% of Runs passing |
Run status
Blue Ocean represents the run status of a Pipeline/item or one of its branches using a consistent set of icons throughout.
| Icon | Status |
|---|---|
|
|
In Progress |
|
|
Passed |
|
|
Unstable |
|
|
Failed |
|
|
Aborted |
Was this page helpful?
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.
Getting started with Blue Ocean
-
Installing Blue Ocean
- On an existing Jenkins instance
- As part of Jenkins in Docker
- Accessing Blue Ocean
- Navigation bar
- Switching to the classic UI
This section describes how to get started with Blue Ocean in Jenkins. It includes instructions for setting up Blue Ocean on your Jenkins instance, how to access the Blue Ocean UI, and returning to the Jenkins classic UI.
|
Blue Ocean status
Blue Ocean will not receive further functionality updates. Blue Ocean will continue to provide easy-to-use Pipeline visualization, but it will not be enhanced further. It will only receive selective updates for significant security issues or functional defects. |
Installing Blue Ocean
You can install Blue Ocean using the following methods:
-
As a suite of plugins on an existing Jenkins instance.
-
As a part of Jenkins in Docker.
On an existing Jenkins instance
When Jenkins is installed on most platforms, the Blue Ocean plugin and all necessary dependent plugins, which compile the Blue Ocean suite of plugins, are not installed by default.
Plugins can be installed on a Jenkins instance by any Jenkins user who has the Administer permission. This is set through Matrix-based security . Jenkins users with this permission can also configure the permissions of other users on their system. Refer to the Authorization section of Managing Security for more information.
To install the Blue Ocean suite of plugins to your Jenkins instance:
-
Ensure you are logged in to Jenkins as a user with the Administer permission.
-
From the Jenkins home page, select Manage Jenkins on the left and then Manage Plugins .
-
Select the Available tab and enter
blue oceanin the Filter text box. This filters the list of plugins based on the name and description.
-
Select the box to the left of Blue Ocean , and then select either the Download now and install after restart option (recommended) or the Install without restart option at the bottom of the page.
-
It is not necessary to select other plugins in this list. The main Blue Ocean plugin automatically selects and installs all dependent plugins, composing the Blue Ocean suite of plugins.
-
If you select the Install without restart option, you must restart Jenkins to gain full Blue Ocean functionality.
-
Refer to the the Managing Plugins page for more information. Blue Ocean does not require additional configuration after installation. Existing Pipelines and projects will continue to work as usual.
The first time you create a Pipeline in Blue Ocean for a specific Git server, Blue Ocean prompts you for your Git credentials to allow you to create Pipelines in the repositories.
This is required since Blue Ocean can add a
Jenkinsfile
to your repositories.
|
As part of Jenkins in Docker
The Blue Ocean suite of plugins is not bundled with the official Jenkins Docker image,
jenkins/jenkins
, which is available from the Docker Hub repository.
Read more about running Jenkins and Blue Ocean inside Docker in the Docker section of the installing Jenkins page.
Accessing Blue Ocean
Once a Jenkins environment has Blue Ocean installed and you log in to the Jenkins classic UI, you can access the Blue Ocean UI by selecting Open Blue Ocean on the left side of the screen.
Alternatively, you can access Blue Ocean directly by appending
/blue
to the end of your Jenkins server’s URL.
For example
https://jenkins-server-url/blue
.
If your Jenkins instance:
-
Already has existing Pipeline projects or other items present, the Blue Ocean Dashboard displays.
-
Is new or does not have projects or other items configured, Blue Ocean displays a Welcome to Jenkins pane with a Create a new Pipeline button. You can select this to begin creating a new Pipeline project. For more information, refer to the Creating a Pipeline page for more information on creating a Pipeline project in Blue Ocean.
Navigation bar
The Blue Ocean UI has a navigation bar along the top of its interface, allowing you to access the different views and features.
The navigation bar is divided into two sections:
-
A common section along the top of most Blue Ocean views.
-
A contextual section below.
The contextual section is specific to the current Blue Ocean page you are viewing.
The navigation bar’s common section includes the following buttons:
-
Jenkins : Selecting the Jenkins icon takes you to the Dashboard or reloads this page if you are already viewing it.
-
Pipelines : This also takes you to the Dashboard. If you are already on the Dashboard, this option reloads the page. This button serves a different purpose when you are viewing a Pipeline run details page.
-
Administration : This takes you to the Manage Jenkins page of the Jenkins classic UI. This button is not available if you do not have the Administer permission. Refer to the Authorization section of the Managing Security page for more information.
-
Go to classic icon: This takes you back to the Jenkins classic UI. Read more about this in Switching to the classic UI.
-
Logout : This logs out your current Jenkins user and returns you to the Jenkins login page.
Views that use the common navigation bar add another bar below it. This second bar includes options specific to that view. Some views replace the common navigation bar with one specifically suited to that view.
Switching to the classic UI
Blue Ocean does not support some legacy or administrative features of Jenkins that are necessary to some users.
If you need to access these features, select the Go to classic icon at the top of a common section of Blue Ocean’s navigation bar.
Selecting this button takes you to the equivalent page in the Jenkins classic UI or the most relevant classic UI page that parallels the current page in Blue Ocean.
Was this page helpful?
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.
Blue Ocean
- What is Blue Ocean?
-
Frequently asked questions
- Why does Blue Ocean exist?
- Where is the name from?
- What does this mean for my plugins?
- What technologies are currently in use?
- Where can I find the source code?
- Join the Blue Ocean community
This chapter covers all aspects of Blue Ocean’s functionality, including how to:
-
get started with Blue Ocean, which covers how to set up Blue Ocean in Jenkins and access the Blue Ocean interface.
-
create a new Pipeline project in Blue Ocean.
-
use Blue Ocean’s dashboard.
-
use the Activity view, where you can access your current and historic run data, your Pipeline’s branches, and any open pull requests.
-
use the Pipeline run details view to access details such as console output, for a particular Pipeline or item run.
-
use the Pipeline editor to modify Pipelines as code, which you can then commit to source control.
This chapter is intended for Jenkins users of all skill levels, but beginners may need to refer to the Pipeline chapter to understand some topics covered here.
For an overview of content in the Jenkins User Handbook, refer to user handbook overview.
|
Blue Ocean status
Blue Ocean will not receive further functionality updates. Blue Ocean will continue to provide easy-to-use Pipeline visualization, but it will not be enhanced further. It will only receive selective updates for significant security issues or functional defects. Alternative options for Pipeline visualization, such as the Pipeline: Stage View and Pipeline Graph View plugins, are available and offer some of the same functionality. While not complete replacements for Blue Ocean, contributions are encouraged from the community for continued development of these plugins. The Pipeline syntax snippet generator assists users as they define Pipeline steps with their arguments. It is the preferred tool for Jenkins Pipeline creation, as it provides online help for the Pipeline steps available in your Jenkins controller. It uses the plugins installed on your Jenkins controller to generate the Pipeline syntax. Refer to the Pipeline steps reference page for information on all available Pipeline steps. |
What is Blue Ocean?
Blue Ocean as it stands provides easy-to-use Pipeline visualization. It was intended to be a rethink of the Jenkins user experience, designed from the ground up for Jenkins Pipeline. Blue Ocean was intended to reduce clutter and increases clarity for all users.
However, Blue Ocean will not receive further functionality or enhancement updates. It will only receive selective updates for significant security issues or functional defects. If you are just starting out, you can still use Blue Ocean, or you may want to consider alternative options such as the Pipeline: Stage View and Pipeline Graph View plugins. These offer some of the same functionality.
To sum up, Blue Ocean’s main features include:
-
Sophisticated visualization of continuous delivery (CD) Pipelines, allowing for fast and intuitive comprehension of your Pipeline’s status.
-
Pipeline editor makes the creation of Pipelines more approachable, by guiding the user through a visual process to create a Pipeline.
-
Personalization to suit the role-based needs of each member of the team.
-
Pinpoint precision when intervention is needed or issues arise. Blue Ocean shows where attention is needed, facilitating exception handling and increasing productivity.
-
Native integration for branches and pull requests , which enables maximum developer productivity when collaborating on code in GitHub and Bitbucket.
If you would like to start using Blue Ocean, please refer to getting started with Blue Ocean.
Frequently asked questions
Why does Blue Ocean exist?
The DevOps world has transitioned from developer tools that are purely functional, to developer tools being part of a "developer experience." It was no longer about a single tool, but the many tools developers use throughout the day, and how they work together to achieve a better workflow for the developer.
Developer tool companies like Heroku, Atlassian, and GitHub have raised the bar for what is considered a good developer experience. Gradually, developers have become more attracted to tools that are not only functional, but are designed to fit into their existing workflow seamlessly. This shift represents a higher standard for design and function, where developers are expecting an exceptional user experience. Jenkins needed to rise to meet this higher standard.
Creating and visualising continuous delivery Pipelines has always been something valuable for many Jenkins users. This has been demonstrated in the plugins that the Jenkins community has created to meet their needs. This also indicates a need to revisit how Jenkins currently expresses these concepts, and consider delivery pipelines as a central theme to the Jenkins user experience.
It is not just continuous delivery concepts, but the tools that developers use every day such as GitHub, Bitbucket, Slack, Puppet, or Docker. It is about more than Jenkins, as it includes the developer workflow surrounding Jenkins, which comprised multiple tools.
New teams can encounter challenges when learning how to assemble their own Jenkins experience. However, the goal to improve their time to market by shipping better software more consistently is the same. Assembling the ideal Jenkins experience is something we, as a community of Jenkins users and contributors, can work together to define. As time progresses, developers' expectations of a good user experience change, and the Jenkins project needs to be receptive to these expectations.
The Jenkins community has worked constantly to build the most technically capable and extensible software automation tool in existence. Not revolutionizing the Jenkins developer experience today could mean that a closed source option attempts to capitalize on this in the future.
Blue Ocean was created to meet such demands of its time. However, as time passed, more modern tools have cropped up to replace it. Now, the time has come for the rise of other plugins of similar functionality. Therefore, any new development or enhancement of Blue Ocean has ceased. If you are interested in contributing to a plugin which serves a similar purpose, you should consider the alternative options as suggested in What is Blue Ocean? section on above.
Where is the name from?
The name Blue Ocean comes from the book Blue Ocean Strategy. This strategy involves looking at problems in the larger uncontested space, instead of strategic problems within a contested space. To put this more simply, consider this quote from ice hockey legend Wayne Gretzky: "Skate to where the puck is going to be, not where it has been."
Does Blue Ocean support freestyle jobs?
Blue Ocean aims to deliver a great experience around Pipeline and compatibility with any freestyle jobs you already have configured in your Jenkins instance. However, you will not benefit from the features built for Pipelines, for example Pipeline visualization.
Blue Ocean was designed to be extensible, so that the Jenkins community could extend Blue Ocean functionality. While there will not be any further functionalities added to Blue Ocean, it still provides Pipeline visualization and other features that users find valuable.
What does this mean for my plugins?
Extensibility is a core feature of Jenkins and being able to extend the Blue Ocean UI is equally important.
The
<ExtensionPoint name=..>
can be used in the markup of Blue Ocean, leaving places for plugins to contribute to the UI.
This means plugins can have their own Blue Ocean extension points.
Blue Ocean itself is implemented using these extension points.
Extensions are delivered by plugins as usual. Plugins must include some additional JavaScript to connect to Blue Ocean’s extension points. Developers that have contributed to the Blue Ocean user experience will have added this JavaScript accordingly.
What technologies are currently in use?
Blue Ocean is built as a collection of Jenkins plugins.
The key difference is that Blue Ocean provides both its own endpoint for HTTP requests, and it delivers HTML/JavaScript via a different path, without using the existing Jenkins UI markup or scripts.
React.js and ES6 are used to deliver the JavaScript components of Blue Ocean.
Inspired by this excellent open-source project, which you can refer to in the building plugins for React apps blog post, an
<ExtensionPoint>
pattern was established that allows extensions to come from any Jenkins plugin with JavaScript.
If the extensions fail to load, their failures are isolated.
Where can I find the source code?
The source code can be found on Github:
-
Blue Ocean
-
Jenkins Design Language
Join the Blue Ocean community
As the development of Blue Ocean has frozen, we do not anticipate or expect any new contributions made to its codebase for new features. However, there are still a few ways you can join the community:
-
Chat with the community and development team on Gitter
-
Request features or report bugs against the
blueocean-plugincomponent in JIRA. -
Subscribe and ask questions on the Jenkins Users mailing list.
-
Developer? We’ve labeled a few issues that are great for anyone wanting to get started developing Blue Ocean. Don’t forget to drop by the Gitter chat and introduce yourself!
Was this page helpful?
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.
Pipeline Editor
- Starting the editor
- Navigation bar
-
Pipeline Settings
- Agent
- Environment
- Stage editor
- Stage configuration
- Step configuration
- Save Pipeline dialog
The Blue Ocean Pipeline Editor is an easy way for anyone to get started with creating Pipelines in Jenkins. It’s also great for existing Jenkins users to start adopting Pipeline.
|
Blue Ocean status
Blue Ocean will not receive further functionality updates. Blue Ocean will continue to provide easy-to-use Pipeline visualization, but it will not be enhanced further. It will only receive selective updates for significant security issues or functional defects. The Pipeline syntax snippet generator assists users as they define Pipeline steps with their arguments. It is the preferred tool for Jenkins Pipeline creation, as it provides online help for the Pipeline steps available in your Jenkins controller. It uses the plugins installed on your Jenkins controller to generate the Pipeline syntax. Refer to the Pipeline steps reference page for information on all available Pipeline steps. |
The editor allows users to create and edit Declarative Pipelines and perform actions such as adding stages or configuring parallel tasks, depending on their needs.
When the user completes their configuration, the editor saves the Pipeline to a source code repository as a
Jenkinsfile
.
If the Pipeline requires further modification, Blue Ocean makes it easy to jump back into the visual editor to modify the Pipeline at any time.
|
Blue Ocean Pipeline Editor limitations
The Blue Ocean Pipeline Editor is a great alternative for Jenkins users, but there are some limitations to its functionality:
|
Starting the editor
To use the editor, a user must first create a Pipeline in Blue Ocean or have at least one existing Pipeline in Jenkins. If editing an existing Pipeline, the credentials for that Pipeline must allow pushing changes to the target repository.
The editor can be launched through the:
-
New Pipeline option from the Blue Ocean dashboard.
-
Branches tab within the Activity view.
-
Edit ( ) in the Pipeline run details view.
Navigation bar
The Pipeline editor includes the standard navigation bar at the top, with a local navigation bar below it. The local navigation bar includes:
-
Pipeline Name - This also includes the branch name.
-
Cancel - Discards changes made to the pipeline.
-
Save - Opens the save Pipeline dialog.
Pipeline Settings
By default, the pane on the right side of the editor displays the Pipeline Settings . Selecting an existing stage or adding a stage displays the stage configuration pane instead. To navigate back to the Pipeline Settings pane, select any empty space in the background of the editor. Within the Pipeline Settings pane, there are two sections that are configurable.
Agent
The Agent section controls which agent the Pipeline uses. This performs the same process as the agent directive. The Image field allows users to configure which container image runs when the Pipeline is active.
Environment
The Environment section allows users to configure environment variables for the Pipeline. This is the same process as the environment directive.
Stage editor
The left pane displays the stage editor UI, which allows users to create or add stages of a Pipeline.
-
To add a stage to the Pipeline, select the icon to the right of an existing stage. Selecting the icon below an existing stage adds a parallel stage.
-
To delete unwanted stages, use the more menu in the stage configuration pane.
After setting the stage name and saving, the name displays above the stage. Stages that contain incomplete or invalid information display a . Pipelines can have validation errors during editing, but saving is blocked until the errors are fixed.
Stage configuration
Selecting a stage in the editor displays the Stage Configuration pane on the right side of the screen. Here, you can modify the name of the stage, delete the stage, and add steps to a stage.
The name of the stage can be set at the top of the stage configuration pane. The more menu, represented by three dots to the right of the stage name, allows users to delete the currently selected stage. Selecting Add step displays the list of available step types. After selecting a step type, the page displays the step configuration pane.
Step configuration
This pane display is based on the step type selected, and contains the necessary fields or controls.
Be sure to provide a strong name for the step, as the name retains its original configuration. Deleting the step and recreating it is the only way to provide a different name. The more menu, represented by three dots to the right of the step name, allows users to delete the current step. Fields that contain incomplete or invalid information display a . Any validation errors must be addressed before saving.
Save Pipeline dialog
Changes to a Pipeline must be saved in source control before running. The Save Pipeline dialog controls the saving of changes to source control.
You can optionally enter a description of the changes before saving. The dialog also provides options for saving changes to the same branch or creating a new branch to save to. Selecting Save & run saves any changes to the Pipeline as a new commit, starts a new Pipeline run based on those changes, and navigates to the Activity view for this pipeline.
Was this page helpful?
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.
Pipeline Run Details View
- Pipeline Run Status
-
Special cases
- Pipelines outside of Source Control
- Freestyle Projects
- Matrix projects
-
Tabs
- Pipeline
- Changes
- Tests
- Artifacts
The Blue Ocean Pipeline Run Details view shows the information related to a single Pipeline Run, and allows users to edit or replay that run. Below is a detailed overview of the parts of the Run Details view.
|
Blue Ocean status
Blue Ocean will not receive further functionality updates. Blue Ocean will continue to provide easy-to-use Pipeline visualization, but it will not be enhanced further. It will only receive selective updates for significant security issues or functional defects. |
-
Run Status - An icon indicating the status of this Pipeline run. The color of the navigation bar matches the status icon.
-
Pipeline Name - The name of this run’s Pipeline.
-
Run Number - The id number for this Pipeline run. Id numbers are unique for each Branch and Pull Request of a Pipeline.
-
View Tabs - Access the Pipeline , Changes , Tests , and Artifacts views with one of the tabs for this run. The default view is "Pipeline".
-
Re-run Pipeline - Execute this run’s Pipeline again.
-
Edit Pipeline - Open this run’s Pipeline in the Pipeline Editor.
-
Configure - Open the Pipeline configuration page in Jenkins.
-
Go to Classic - Switch to the "Classic" UI view of the details for this run.
-
Close Details - Closes the Details view and returns the user to the Activity view for this Pipeline.
-
Branch or Pull Request - The branch or pull request for this run.
-
Commit Id - The commit id for this run.
-
Duration - The duration of this run.
-
Completed Time - When this run was completed.
-
Change Author - Names of the authors with changes in this run.
-
Tab View - Shows the information for the selected tab.
Pipeline Run Status
Blue Ocean makes it easy to see the status of the current Pipeline Run, by changing the color of the top menu bar to match the status:
-
Blue for "In progress"
-
Green for "Passed"
-
Yellow for "Unstable"
-
Red for "Failed"
-
Gray for "Aborted"
Special cases
Blue Ocean is optimized for working with Pipelines in Source Control, but can display details for other kinds of projects. Blue Ocean offers the same tabs for all supported projects types, but those tabs display different information depending on the type.
Pipelines outside of Source Control
For Pipelines that are not based in Source Control, Blue Ocean shows the "Commit Id", "Branch", and "Changes", but those fields are left blank. In this case, the top menu bar does not include the "Edit" option.
Freestyle Projects
For Freestyle projects, Blue Ocean offers the same tabs, but the Pipeline tab only displays the console log output. The "Rerun" or "Edit" options are not available in the top menu bar.
Matrix projects
Matrix projects are not supported in Blue Ocean. Viewing a Matrix project will redirect to the "Classic UI" view for that project.
Tabs
Each tab of the Run Detail view provides information on a specific aspect of a run.
Pipeline
Pipeline is the default tab and gives an overall view of the flow of this Pipeline Run. It shows each stage and parallel branch, the steps in those stages, and the console output from those steps. The overview image above shows a successful Pipeline run. If a particular step during the run fails, this tab automatically defaults to showing the console log from the failed step. The image below shows a failed Run.
Changes
The Changes tab displays the information of any changes made between the most recently completed and current runs. This includes the commit id for the change, change author, message, and date completed.
Tests
The
Tests
tab shows information about test results for this run.
This tab only contains information if a test result publishing step is present, such as the "Publish JUnit test results" (
junit
) step.
If no results are recorded, this table displays a message.
If all tests pass, this tab will report the total number of passing tests.
If there are failures, the tab will display log details from the failures as shown below.
When a previous run has failures, and the current run fixes those failures, this tab notes the fixes and displays their logs.
Artifacts
The
Artifacts
tab shows a list of any artifacts saved using the "Archive Artifacts" (
archiveArtifacts
) step.
Selecting an item in the list downloads it.
The full output log from the Run can be downloaded from this list.
Was this page helpful?
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.
Linux Support Policy
This page documents the Linux support policy for the Jenkins controller and agents.
Scope
Individual Jenkins plugins may set additional requirements for Linux versions on controllers and/or agents. This page does not document such requirements. Please refer to plugin documentation for additional requirements.
Why?
Theoretically, Jenkins can run everywhere where you can run a supported Java version, but there are some limitations in practice. Jenkins core and some plugins include native code or depend on Linux API and subsystems and hence they rely on specific Linux versions. Jenkins platform specific installation packages rely on specific Linux versions.
Support levels
We define multiple support levels for Linux platforms.
| Support level | Description | Platforms |
|---|---|---|
|
Level 1 - Supported |
We run automated package manager installation testing for these platforms and we intend to fix the reported issues in a timely manner.
We recommend either package manager based installations or container based installations for Linux.
Installations may also use
|
|
|
Level 2 - Patches considered |
Support may have limitations and extra requirements. We do not test compatibility, and we may drop support at any time. We consider patches that do not put level 1 support at risk and do not create maintenance overhead. |
|
|
Level 3 - Unsupported |
These versions are known to be incompatible or to have severe limitations. We do not support the listed platforms and we do not accept patches. |
|
References
-
Debian Long Term Support
-
Red Hat Enterprise Linux Life Cycle
-
SUSE Product Support Lifecycle
-
Ubuntu lifecycle and release cadence
Contributing
You are welcome to propose PR’s that add support for other Linux platforms or to share feedback; we will appreciate your contributions! Linux support in Jenkins is Platform Special Interest Group which has a chat, a mailing list, and regular meetings. You are welcome to join these channels.
Version history
-
March 2022 - First version (Discussion in the mailing list, Governance meeting notes and recording)
Servlet Container Support Policy
This page documents the servlet container support policy for the Jenkins controller.
Why?
Jenkins is typically run as a standalone application in its own process. The Jenkins WAR file bundles Winstone, a Jetty servlet container wrapper, and can be started on any operating system or platform with a version of Java supported by Jenkins. This is the preferred way to deploy Jenkins and is fully supported.
Theoretically, Jenkins can also be run as a servlet in a traditional servlet container like Apache Tomcat or WildFly, but in practice this is largely untested and there are many caveats. In particular, support for WebSocket agents is only implemented for the Jetty servlet container.
| Support for traditional servlet containers may be discontinued in the future. |
Support levels
We define multiple support levels for servlet containers.
| Support level | Description | Servlet containers |
|---|---|---|
|
Level 1: Supported |
We run automated testing for these servlet containers, and we intend to fix reported issues in a timely manner. |
The versions of Winstone and Jetty bundled in the Jenkins WAR file. |
|
Level 2: Patches considered |
Support may have limitations and extra requirements. We do not regularly test compatibility, and we may drop support at any time. We consider patches that do not put Level 1 support at risk and do not create maintenance overhead. |
|
|
Level 3: Unsupported |
These versions are known to be incompatible or to have severe limitations. We do not support the listed servlet containers. |
|
References
-
Installation instructions
-
Jetty versions
-
Tomcat versions
-
WildFly 27 release announcement
Contributing
You are welcome to propose PRs that add support or documentation for other servlet containers or to share feedback; we will appreciate your contributions! Servlet container support in Jenkins falls under the Platform Special Interest Group which has a chat, a mailing list, and regular meetings. You are welcome to join these channels.