Blue Ocean is a set of plugins that gives Jenkins a cleaner, more visual user interface, designed especially for pipelines.

Start with the basics. Jenkins is an automation server, a program that stays switched on and does tasks for you, such as building and testing software. A job is the saved description of a task, and a build is one run of that job. A pipeline is a job whose steps are written down as a series of connected phases, called stages, such as Build, Test and Deploy. You interact with Jenkins through a user interface, often shortened to UI: the web pages you see and click in your browser.

Blue Ocean is a project that redesigned that user interface. Instead of the traditional pages full of tables, links and small text, Blue Ocean shows large, colorful pictures of your pipeline. Each stage is a clear shape, each step is a row you can open, and the result of every run is easy to see from across the room. It is delivered as a collection of plugins, meaning add-on pieces that you install into Jenkins. When installed, a link appears that lets you switch from the classic pages to the Blue Ocean pages.

It is important to understand what Blue Ocean is not. It is not a separate automation server. It does not run your builds by itself. It does not replace Git, or your build tools, or your test tools. It is a viewing and editing layer that sits on top of Jenkins and talks to the same engine, the same jobs and the same build history.

Your first five minutes with it

If you open Blue Ocean for the first time, expect a very different feeling from the classic pages. The first screen is the dashboard, with a large, calm layout and few buttons. Your pipelines appear as wide rows with a colored strip on the left, and a search box at the top lets you jump to a name. Click any pipeline and you land on a page of recent runs, each shown as a row with a number, a colored mark, the branch, a short message from the code change, and the time. Click a run and the pipeline picture opens. In five minutes, a beginner can usually find a failed run, see which stage was red, and open its log, a journey that can take much longer on the older pages. This gentle first impression is the main reason Blue Ocean became popular with people new to Jenkins.

What Blue Ocean offers, at a glance

Blue Ocean was born from a simple complaint: Jenkins was powerful, but it did not look or feel modern.

Jenkins began life in the mid-2000s, when web pages were simple and functional. Its screens grew over the years as new features and plugins were added, and they were designed by many hands at different times. For experienced users this was fine, because they knew where everything was. For newcomers it was a maze. Many people who might have loved Jenkins bounced off its appearance before ever discovering how capable it was.

At the same time, Jenkins introduced pipelines, a new and much better way to describe delivery as code. But the classic pages were built around the older idea of a single job with a list of steps, not a pipeline with parallel branches and named stages. Showing a pipeline properly needed new pictures and new layouts. The project therefore set out to create a fresh interface designed from the start for pipelines, and it gave the project a memorable name, Blue Ocean.

The design ideas behind it

The people who designed Blue Ocean followed a few simple ideas that are worth knowing, because they explain how it looks. The first was clarity: show the most important fact, whether the run is healthy, in the largest and simplest form, with a color anyone can read. The second was focus on failure: when something breaks, take the user straight to the broken step, instead of asking them to search. The third was context: show the branch, the pull request and the change message beside every run, so the reader knows why the run exists. The fourth was gentle creation: let a beginner build a pipeline by clicking, and teach them by showing the file that results. These four ideas, clarity, focus, context and gentle creation, are useful lessons for anyone designing tools for other people.

A few small ideas explain almost everything about Blue Ocean. Learn them once and the rest is easy.

Words you will meet only in Blue Ocean

Notice that Blue Ocean often says run where classic Jenkins says build. They mean the same thing: one numbered execution. Whichever word you use, you are pointing to the same record in the same build history.

Classic and Blue Ocean side by side

When Blue Ocean is installed, Jenkins now has two faces. The classic interface is the original set of pages. It can do everything: manage every setting, every plugin and every type of job. The Blue Ocean interface is the newer face. It focuses on pipelines, and does not cover every part of Jenkins. Both look at the same jobs and builds, so a build you start in one appears in the other.

Blue Ocean is a layer, not a new engine. Seeing where the layer sits makes everything else clear.

flowchart LR
    User["Developer or Tester"] --> Classic["Classic Jenkins Pages"]
    User --> BO["Blue Ocean Pages"]
    Classic --> API["Jenkins Web Interface and API"]
    BO --> API
    API --> Ctrl["Jenkins Controller"]
    Ctrl --> Queue["Build Queue"]
    Queue --> Agent["Agents"]
    Ctrl --> Home["Jobs and Build History in JENKINS_HOME"]
    Ctrl --> Git["Git Repository"]

Reading the diagram

Start on the left with the user. A person can open either the classic pages or the Blue Ocean pages in their browser. Both of them talk to the same Jenkins web interface and API, which is the set of doorways that Jenkins offers for other programs and pages to ask for information and give orders. Behind that door sits the Jenkins controller, the main server. It keeps the build queue, sends work to agents, stores jobs and build history in its home folder, and talks to the Git repository. Blue Ocean adds nothing new behind the door. It only draws the information in a different style.

What this design means for you

• No data is lost or duplicated. Builds, logs and results live in one place, and both faces read from it.
• You can switch at any time. A link on each side takes you to the other.
• Removing Blue Ocean does not delete your jobs. Because it is only a layer, uninstalling it leaves your pipelines and history untouched.
• It relies on plugins. As with any plugin, it must be kept compatible with your Jenkins version, or it may stop working properly.

Blue Ocean is optional. Here is how it appears in Jenkins, in simple terms.

Installing it

Blue Ocean is installed like any other plugin. An administrator opens the plugin management page, searches for Blue Ocean, and installs it. Jenkins downloads the group of plugins and, after a restart if needed, the new interface becomes available. Only administrators should do this, because it changes what runs on the controller.

Opening it

Once installed, a link labeled Open Blue Ocean appears in the left-hand menu of many classic pages. Clicking it takes you to the Blue Ocean dashboard, a page that lists your pipelines in a clean, spacious layout. Inside Blue Ocean, there is a button to go back to the classic Jenkins interface whenever you need to.

Who can use it

Blue Ocean follows the same permissions as classic Jenkins. If you are not allowed to see a job in the classic pages, you are not allowed to see it in Blue Ocean either. If you may start builds in one, you may start them in the other. No permissions are bypassed.

The two screens you will see most in Blue Ocean are the dashboard and the pipeline run view.

The dashboard

The dashboard lists your pipelines as large rows or cards. Each shows its name, a colored status, the latest branch or pull request activity, and how long ago it last ran. You can mark pipelines as favorites, so the ones you care about rise to the top. This is a friendlier starting page than a long table of every job on the server.

The run view

Click a pipeline and then a run, and you see the heart of Blue Ocean: a picture of the pipeline. The stages are drawn from left to right as connected circles or boxes. Stages that ran in parallel are drawn one above the other. A green mark means success, red means failure, grey means skipped or not yet run, and a moving indicator shows the stage that is running right now. Below the picture, the steps of the chosen stage appear as rows. Click a row and its log opens in place.

flowchart LR
    S["Start"] --> B["Build: passed"]
    B --> T1["Unit tests: passed"]
    B --> T2["Browser tests: failed"]
    T1 --> P["Package: skipped"]
    T2 --> P
    P --> D["Deploy: not run"]

Reading the diagram

The Build stage passed, so the pipeline moved on. Then two stages ran side by side, in parallel: Unit tests passed, but Browser tests failed. Because one branch failed, the Package stage was skipped, and Deploy never ran, which is the fail-fast behavior. At a glance, without reading a single line of log, you know that the problem is in the browser tests. Blue Ocean would then let you click that stage and open its log immediately.

Logs, changes and tests inside the run

Beyond the picture, each run carries three kinds of detail that Blue Ocean lays out tidily. The logs are split by step, so you open only the step that failed, instead of scrolling through thousands of lines. The changes tab lists the code changes that went into the run, each with an author and a short message, so you can guess which change might be responsible for a failure. The tests tab lists which tests passed, failed or were skipped, and lets you open the failing ones to read their messages. Together, these three answer the classic detective questions: what failed, what changed, and which checks noticed.

A good habit is to read a failed run in this order. First glance at the picture to find the red stage. Then open that stage’s failing step and read the last few lines of its log. Then open the changes tab to see what was new. Finally, check the tests tab if the failure came from a test stage. This routine takes less than two minutes once it becomes a habit, and it works for almost every failure.

Blue Ocean lets you create a simple pipeline by pointing and clicking, and it writes the recipe file for you.

Writing a pipeline recipe from scratch can feel intimidating to a beginner. Blue Ocean offers a visual editor. You start by choosing where your code lives, such as a Git repository, and then you add stages by clicking a plus button. For each stage, you add steps from a list, such as running a command or publishing a report. On the side, settings such as which agent to use can be filled in with simple forms. When you save, Blue Ocean writes a Jenkinsfile and stores it in your repository, usually on a branch of your choice.

What creating a pipeline looks like, step by step

Notice that the result is an ordinary text file in your repository. That is the great strength of this approach. Even if you stop using Blue Ocean tomorrow, the file stays, and any other tool or person can read and change it. The editor is just a friendly way of writing the first draft.

What the editor is good for

• First steps. A newcomer can create a working pipeline in minutes and see how stages and steps fit together.
• Learning. The generated Jenkinsfile shows what the clicks mean, so it teaches by example.
• Simple pipelines. Straightforward build, test and deploy flows are easy to draw.

Its limits

• Style limits. The editor works with the declarative style of pipeline. It cannot open every hand-written or scripted pipeline.
• Complex logic. Advanced conditions, shared libraries and unusual features are better written by hand.
• Round trips. A pipeline heavily edited by hand may not open cleanly in the visual editor afterward.

One of Blue Ocean’s most loved features is how it shows the health of every branch and every proposed change.

Modern teams work in branches, separate copies of the code where new work can happen without disturbing others. When work is ready, a developer opens a pull request, a formal request to merge the branch into the main line. A multibranch pipeline in Jenkins automatically creates a pipeline for each branch and pull request. Blue Ocean displays them in tabs, one for branches, one for pull requests, and a summary of the latest run of each.

Why this helps teams

A reviewer can look at the pull request list and quickly see which changes pass their checks. A developer can spot that their branch failed within minutes of pushing code, without hunting through a long list of jobs. This encourages the healthy habit of testing changes before they join the main line, when problems are cheapest to fix.

A run that you watch in Blue Ocean goes through the same journey as any Jenkins build. Only the display is different.

Reading the signals during a run

The tabs of a run

How stage names shape the picture

The pipeline picture is only as good as the stage names behind it. A pipeline whose stages are called Build, Unit Tests, Integration Tests, Package and Deploy tells a clear story at a glance. A pipeline with one giant stage called Everything gives a single blob, and the picture adds nothing. Because Blue Ocean draws exactly what the recipe describes, improving the picture means improving the recipe: split the work into meaningful stages, give each a short, honest name, and run independent work in parallel. A good side effect is that the same changes make the classic views, the logs and the build history easier to read too.

Blue Ocean is one of several ways to see a pipeline. Knowing the others helps you choose calmly.

A simple way to decide

flowchart TD
    Q1["Do you use pipelines?"] -->|"No"| A1["Classic pages are enough"]
    Q1 -->|"Yes"| Q2["Do users find classic pages hard to read?"]
    Q2 -->|"No"| A2["Keep classic pages and Stage View"]
    Q2 -->|"Yes"| Q3["Do you want a lighter option?"]
    Q3 -->|"Yes"| A3["Try a pipeline graph plugin in the classic pages"]
    Q3 -->|"No"| Q4["Is Blue Ocean still supported for your Jenkins version?"]
    Q4 -->|"Yes"| A4["Trial Blue Ocean on a test server first"]
    Q4 -->|"No"| A3

Reading the diagram

Start at the top with the question Do you use pipelines? If not, the classic pages already suit you, and no special viewer is needed. If yes, ask whether your users find the classic pages hard to read. If they do not, keep the classic pages together with the light Stage View grid. If they do, ask whether you would prefer a lighter option. A pipeline graph plugin gives you pictures inside the classic pages, with less weight. If you still want the full Blue Ocean experience, check that it is supported for your Jenkins version, and always trial it on a test server first. This path is only a guide, but it shows that Blue Ocean is one good answer among several, not the only one.

Where things are heading

As far as I know, the Jenkins project has been improving the classic interface and introducing lighter plugins that bring pipeline graphs and modern styling directly into it, so that people do not need to switch to a separate interface. If you are choosing a viewing tool for a new setup, it is wise to look at the current recommendations on the official Jenkins site, because this area has been changing.

Any plugin adds code to your controller. A modern-looking screen is welcome, but it should never weaken your defenses.

Who can see what

Blue Ocean does not create a second set of users. It uses the same sign-in and the same permissions as the rest of Jenkins. A person who may only view a job sees its runs but cannot start or change them. A person who may build can start runs. A person who may configure can edit pipelines, including through the visual editor. This means an administrator can review access in the usual place and be sure that it covers both interfaces. It also means that a mistake in permissions is a mistake in both places, so it is worth checking roles carefully whenever a new team joins.

The repository connection

When you create a pipeline through the visual editor, Jenkins needs credentials to read your repository, and sometimes to write a Jenkinsfile back to it. Give it only the access it needs. A read-only key for reading, and a narrowly scoped key for writing to specific branches, is far safer than an all-powerful account.

A prettier interface should not make Jenkins slower. A few simple checks keep it healthy.

Logs in a friendlier form

Blue Ocean splits the console log into sections, one for each step, so you can open only what you need. The full raw log is still available, and it is the same text stored by classic Jenkins. When a build prints millions of lines, even a friendly display will struggle, so keep logs meaningful: print progress and errors, not every detail.

Metrics tools

Blue Ocean shows the state of builds, but it is not a metrics tool. For long-term numbers such as build duration, success rate and queue time, teams send data to monitoring systems. A common setup lets Prometheus, a widely used metrics collector, gather figures from Jenkins, while Grafana draws charts and raises alerts. Use pictures from Blue Ocean for quick reading, and use monitoring for trends over months.

Living with Blue Ocean day to day

Teams that keep Blue Ocean running for a long time usually settle into a small routine. An administrator checks the plugin update list once a month and applies updates on a test copy before the real server. Someone reviews, every quarter, whether people still open the Blue Ocean pages, using the simple test of asking the team. New team members get a short walkthrough of both interfaces, so that nobody is confused about where to look. And the team keeps a short note explaining which interface is preferred for which task, for example pictures and pull requests in Blue Ocean, and settings and administration in the classic pages. These small habits cost very little time, and they prevent the confusion that two interfaces can cause.

Blue Ocean brings real pleasures and real costs. Knowing both helps you decide with open eyes.

The hidden cost of ownership

Every tool you install has a cost beyond the first click. Somebody must update it, watch its security notices, test it after each Jenkins upgrade, answer questions about it and explain it to new teammates. For a small group of plugins used by everyone, that cost is easily worth paying. For a large group of plugins used by only two people, it may not be. When you weigh Blue Ocean, count these ongoing hours honestly, and compare them with the time it saves your users. Teams that do this calmly usually make a good choice, whichever way it goes.

Trade-offs to think about

A pattern is a proven way to solve a common problem. An anti-pattern is a habit that looks fine and causes pain later.

Patterns worth copying

A pattern for teaching with pictures

When you teach a new person about Jenkins, start with the picture and end with the file. First show a run in the pipeline view, and let them find the red stage and open its log. Then open the Jenkinsfile in a text editor and show how each stage in the picture matches a block of text. Finally, let them change one small thing, such as a stage name, push it, and watch the picture change. This three-step lesson connects the friendly picture to the real recipe, so the learner never thinks of the picture as magic. It also builds the habit of treating the file as the truth, which protects the team if the viewing tool ever changes.

Habits to avoid

These are lessons experienced teams usually learn the hard way. You can learn them the easy way, by reading them now.

Best practices

• Check the current status first. Read the plugin page and Jenkins announcements before adopting or keeping Blue Ocean.
• Try before you install widely. Test it on a spare server and ask real users.
• Keep the pipeline in the repository. The recipe is what matters, not the screen that draws it.
• Use the editor to learn. Read the file it writes, and move to text as pipelines grow.
• Name stages clearly and keep them stable. The picture is only as good as the names.
• Use parallel stages wisely. They shorten runs, and the picture makes them easy to follow.
• Use webhooks. Fresh pictures need fresh notifications.
• Keep the classic interface handy. Some tasks and settings live only there.
• Keep plugins updated. Follow security advisories and update on a schedule.
• Use least privilege. Give the repository credentials only the access they need.
• Give pipelines owners. A red picture with a name gets fixed sooner.

Common mistakes

• Believing Blue Ocean is a separate product. It is a layer on the same Jenkins.
• Expecting every feature to appear in it. Many settings live only in the classic interface.
• Relying on the editor for advanced pipelines. It suits simple cases.
• Ignoring maintenance status. A tool in low maintenance may not get the fixes you need.
• Installing it on production without testing. A large group of plugins deserves a trial run.
• Forgetting permissions. The interface is new, but the rules are the same.
• Judging build health by colors alone. Read the details, trends and tests too.

A worked example: a small team decides about Blue Ocean

Imagine a team of six who have just moved their builds to pipelines. Two of the newer developers find the classic pages confusing, and ask whether there is something friendlier. The team lead sets up a spare Jenkins, installs Blue Ocean, and lets everybody try it for a week. The newcomers love the pipeline pictures and the failure pinpointing. The senior engineers notice that some settings are missing, and that the plugin group is large. They also read that the project has moved its focus elsewhere, and look at lighter graph plugins that fit inside the classic pages.

In the end, they choose a middle path. They keep the classic interface as the main tool, add a lighter pipeline graph plugin for pictures, and use the visual editor on the spare server only when teaching new members. Notice how they decided: they tried it, asked real users, checked its status, weighed the cost in plugins, and picked what fit. That process is worth copying for any tool.

Sooner or later something looks wrong. A calm routine finds the cause quickly.

When to ask for help

Some problems are worth escalating rather than fighting alone. If several users see the same odd behavior after a plugin update, roll back to the previous version on a test copy and compare. If the error messages point to a plugin dependency, read the plugin’s page for known issues. If the interface breaks only for one pipeline, try creating a tiny test pipeline to see whether the problem is in your file or in the tool. And if you find yourself spending more time repairing the viewer than watching your builds, that is a strong sign to reconsider the tool. Asking the community, with a clear description, the versions involved and the steps to reproduce, usually gets a useful answer quickly.

Common situations and their usual causes

Blue Ocean appeared in many teams during its popular years. Here is how the ideas look in practice.

Lessons that repeat across teams

Look across these examples and a few lessons appear again and again. Interfaces come and go, but pipelines as code and build history remain. Pictures help newcomers and reviewers, and numbers help managers. Tools should be tried before they are adopted widely, and reviewed again as their status changes. And whatever viewer you use, keep secrets safe, keep plugins updated and keep permissions tight. None of this needs a large budget. A small team can follow every one of these habits from the first week.

Blue Ocean was Jenkins’ modern face for pipelines. Understanding it as a layer, not a replacement, keeps decisions simple.