Getting started with Blue Ocean

This section describes how to get started with Blue Ocean in Jenkins. It includes instructions for setting up Blue Ocean on your Jenkins instance, as well as how to access the Blue Ocean UI and return to the Jenkins classic UI.

Installing Blue Ocean

Blue Ocean can be installed using the following methods:

On an existing Jenkins instance

When Jenkins is installed on most platforms, the Blue Ocean plugin and all its other dependent plugins (which form the Blue Ocean "suite of plugins") are not installed by default.

To install the Blue Ocean suite of plugins on an existing Jenkins instance, your Jenkins instance must be running Jenkins 2.7.x or later.

Plugins can be installed on a Jenkins instance by any Jenkins user who has the Administer permission (set through Matrix-based security). Jenkins users with this permission can also configure the permissions of other users on their system. Read more about this in the Authorization section of Managing Security.

To install the Blue Ocean suite of plugins to your Jenkins instance:

  1. If required, ensure you are logged in to Jenkins (as a user with the Administer permission).

  2. From the Jenkins home page (i.e., the Dashboard of the Jenkins classic UI), click Manage Jenkins on the left and then Manage Plugins in the center.

  3. Click the Available tab and type blue ocean into the Filter text box, which filters the list of plugins to those whose name and/or description contains the words "blue" and "ocean."

    Blue Ocean plugins filtered

  4. Select the Blue Ocean plugin’s check box near the top of the Install column and then click either the Download now and install after restart button (recommended) or the Install without restart button at the end of the page.

    • There is no need to select the checkboxes of the other plugins in this filtered list. The main Blue Ocean plugin has other plugin dependencies (constituting the Blue Ocean suite of plugins), which will automatically be selected and installed when you click one of these "Install" buttons.

    • If you chose the Install without restart button, you might need to restart Jenkins in order to gain full Blue Ocean functionality.

Read more about how to install and manage plugins on the Managing Plugins page.

Blue Ocean requires no additional configuration after installation, and existing Pipelines projects and other items such as freestyle projects will continue to work as usual.

Be aware, however, that the first time a Pipeline is created in Blue Ocean for a specific Git server (i.e., GitHub, Bitbucket, or an ordinary Git server), Blue Ocean prompts you for credentials to access your repositories on the Git server in order to create Pipelines based on those repositories. This is required since Blue Ocean can write Jenkinsfiles 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), 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, after logging in to the Jenkins classic UI, you can access the Blue Ocean UI by clicking Open Blue Ocean on the left.

Open Blue Ocean link

Alternatively, you can access Blue Ocean directly by appending /blue to the end of your Jenkins server’s URL - e.g., https://jenkins-server-url/blue.

If your Jenkins instance:

  • Already has existing Pipeline projects or other items present, then the Blue Ocean Dashboard is displayed.

  • Is new or has no Pipeline projects or other items configured, then Blue Ocean displays a Welcome to Jenkins box with a Create a new Pipeline button you can use to begin creating a new Pipeline project. Read more about this in Creating a Pipeline.

    Welcome to Jenkins - Create a New Pipeline message box

The Blue Ocean UI has a navigation bar along the top of its interface, which allows you to access the different views and other features of Blue Ocean.

The navigation bar is divided into two sections - a common section along the top of most Blue Ocean views and 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 logo - takes you to the Dashboard or reloads this page if you are already viewing it.

  • Pipelines - also takes you to the Dashboard or does nothing if you are already viewing the Dashboard. This button serves a different purpose when you are viewing a Pipeline run details page.

  • Administration - takes you to the Manage Jenkins page of the Jenkins classic UI.
    Note: This button is not available if your Jenkins user does not have the Administer permission (set through Matrix-based security). Read more about this in the Authorization section of Managing Security.

  • Go to classic icon - takes you back to the Jenkins classic UI. Read more about this in Switching to the classic UI.

  • Logout - Logs out your current Jenkins user and returns to the Jenkins login page.

Views that use the standard navigation bar will add another bar below it, with 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 leave the Blue Ocean user experience to access these features, click the Go to classic icon at the top of a common section of Blue Ocean’s navigation bar.

Go to classic icon

Clicking 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.