New User Experience For CloudBees Jenkins Enterprise

CloudBees Jenkins Enterprise helps teams accelerate software delivery through seamless collaboration around the software delivery process.

As DevOps needs rapidly evolve, enterprises require confidence that they are equipping their teams with the most feature-rich, reliable and secure Jenkins-based continuous delivery platform possible. With the new version of CloudBees Jenkins Enterprise, enterprises can onboard new projects and new teams quickly, via pre-configured security and built-in integrations to code repositories. This fast set-up enables organizations to accelerate their DevOps journey.

Installing the New User Experience For CloudBees Jenkins Enterprise

Getting the New User Experience For CloudBees Jenkins Enterprise is as easy as installing a plugin in your Operations Center.

Navigate to Manage Jenkins / Manage Plugins / Available, select Operations Center New User Experience Preview and click on Download now and install after restart to install the plugin and its dependencies.

The process will install some (not all) Pipeline and Blue Ocean components in Operations Center, but it will not add any new item to the New Item page (only tooling and API plugins are installed)

Once the installation is completed you should see a new link in the left menu bar, Open Blue Ocean:

open blue ocean
Tip
The New UX is only available for CloudBees Jenkins Enterprise. Related plugins will not be installable or available in Update Centers for older products (i.e. CloudBees Jenkins Platform).

How to create a new Team

Once you have installed the New User Experience For CloudBees Jenkins Enterprise plugin, creating a Team is very simple.

On the Operations Center main page, click the Open Blue Ocean link on the left menu:

open blue ocean

On the following screen, you will be presented with the existing Teams, if any:

teams list

Click on the Create a team button on the left.

Then, on the next screen:

  • Name your team - you will be able to change it whenever you like;

  • Select an icon and a color;

  • Add new team members by entering their Jenkins username or group id. The Jenkins username is the identifier you enter in the login page when you authenticate, the group id is the name of the external group as it is loaded by your authentication realm if it supports external groups. You can change the role of the new team member easily;

  • Select your Team master creation recipe. Recipes define a kind of template (list of plugins to install, …​) for creating your team masters (See Team Master Creation Recipes below for more details).

  • Click on Create team

team creation

The creation of the Jenkins Team Master should take a few dozens of seconds [1]. Once the Team Master is created, it is immediately accessible and usable by the team members.

The New User Experience For CloudBees Jenkins Enterprise comes out of the box with a brand new easy to use authorization model. This includes the following roles:

  • Team Admin: administrator of the Team Master.

  • Team Member: read, write and execute permission on the pipelines.

  • Team Guest: read only.

Tip
If additional customized roles are needed they can be added using the Command Line Interface. See the section "Command Line Interface" below.

How to manage team members

Accessing the team settings

After you have created a team, you can edit the team settings by clicking on the Administration on the top right. It will take you to the team list.

From there, click on the team you wish to edit. You will be able to change anything: the team display name, the icon and its color, and the members of that team.

Team members management

As introduced previously, the New User Experience For CloudBees Jenkins Enterprise ships with a simple and easy to use new authorization model.

Adding user or group ID is straightforward: type the ID, hit Enter, then select the role you want in the combobox next to the user.

add new member

Then click Save when you are done.

The different roles

The authorization model offers the following roles:

Team admin

Allows you to modify anything on the team.

Note
This is not a global role - someone can be a Team admin on one team, but not another. A Team admin only has permission to modify teams on which they have the Team admin role.
Team member

Gives you read, write and execute permission on the pipelines of the team master.

Team guest

Gives you read access on the pipelines of the team master.

Team Master Creation Recipes

Starting with the New User Experience For CloudBees Jenkins Enterprise version 1.1.1, we introduced a new feature that lets you define how a Team should be created.

By default, there are two predefined recipes:

Basic (basic)

Includes a basic set of plugins designed to help get you started with the New User Experience For CloudBees Jenkins Enterprise

Java & Web Development (java-web)

Includes some plugins deemed useful for Java & Web development (FindBugs, Warnings, Tasks, Pipeline Maven, Node JS, etc.).

Using the CLI

The team creation CLI has been adapted to accept a new provisioningRecipe attribute.

From version 1.2.1, the CLI was extended to allow you to create your own recipes, and from version 2.138.1.3, the recipes allow to specify the installation of a plugin catalog. See the commands in more details below.

Note

Currently, the only configurable parameters are the list of plugins to install and the plugin catalog to configure. However, additional configuration parameters are planned for future releases. Customer feedback helps orient upcoming features. Therefore, please provide feedback if you have specific configurations you would like to see.

When the recipe specifies a plugin catalog, such a catalog is installed during the creation of the Team Master. If the plugin catalog cannot be installed (for example, because it is not compatible with the Team Master), then the Team master is still created but without the plugin catalog.

Integration with the Role-Based Access Control plugin

The New User Experience For CloudBees Jenkins Enterprise ships with an integration with the Role-Based Access Control plugin (exclusively when used on Operations Center).

Someone having the Jenkins.ADMINISTER permission on the underlying Managed Master for that team will automatically be made Team admin.

When to use a Team Master, when to use a Managed Master

New User Experience For CloudBees Jenkins Enterprise introduces the new concept of Team Master, however the existing Managed Master functionalities will still be available to users who require the classic approach.

When a new team in the organization is going to be on-boarded in CloudBees Jenkins Enterprise the first question to answer is: should I use a Team Master or a Managed Master? The answer depends mainly on authorization needs.

As explained in Team Members Management the New User Experience comes with a simplified and easy to use authorization model which offers 3 roles for team members: Team admin, Team member or Team guest.

If you need more fine grained authorization settings then use a classic Managed Master and Role-Based Access Control.

How to migrate a team from a Managed Master to a "Team Master"

It is not possible to transform a Managed Master into a Team Master, so the migration path is based on the CloudBees Jenkins Enterprise feature Move/Copy.

Although this document points to Move and Copy as equivalent methods of migration, it is strongly recommended to use Copy, so a version of the original item is always available as a recovery backup.

Even after a successful migration, the original master should be kept around for validation and recovery purposes. As there are manual steps in the migration, it is possible to forget replicating some required items (credentials or global configuration usually) so having the original master at hand is going to be useful. The Backup Plugin would be also helpful to keep a full backup of the original master.

Before starting the migration

The starting point is a CloudBees Jenkins Enterprise cluster where a Managed Master (to be migrated) is connected to Operations Center. The Team Master has been created in the same cluster so it is connected to the same Operations Center.

both masters connected

Also make sure the Team Master is aligned in terms of plugins with the Managed Master (the Move or Copy dialog shows a warning about this in any case).

The migration

Pipelines often use peripheral data (such as credentials, shared libraries, tools configuration, etc) which is outside the Pipeline definition itself, so a different migration process is required for the migration of this data.

Migrate Credentials

Pipelines often use credentials defined in Jenkins. Those credentials need to be migrated separately (unless they are defined in the folder containing the Pipeline/s).

  • Folder scoped credentials: nothing to do, the Move/Copy operation takes care of them.

folder credentials

  • Jenkins (top level) scoped credentials: manual migration is needed, either recreate them in the folder before moving/copying it or recreate them in the Team Master.

global credentials

Migrate Pipelines

Use the Move/Copy CloudBees Jenkins Enterprise feature to move pipelines to the new Team Master.

mcp item

Each Team Master has a special folder (created automatically) which contains all the Pipelines (when created) and Team configuration.

Make sure pipelines are moved/copied into the Team Folder on the target master. The Team Folder is at the root level on the Team Master and its name is the same as the Team Master name.

mcp path

Migrated items should be visible in your new Team now:

migrated

Global Configuration

Any Jenkins global configuration (i.e anything under Manage Jenkins) which affects Pipeline execution has to be manually migrated. For example, Tools Configuration (Maven, JDK, etc) or Configure System settings (i.e. global GitHub or Bitbucket configuration).

Command Line Interface

The new UX comes with an additional set of Command Line endpoints to manage Teams, Team Members, Team Roles and permissions. All commands can be used in two ways:

  • Human friendly: more fine grained operations that operate on a single entity (i.e. change the role of a member)

  • Machine friendly: a JSON file is used as input and all changes are done in a single transaction (the --put option enables this mode)

Input and output messages are JSON, and usually the output of a read command can be used as input for a write.

These I/O messages follow the structure of a "data" element (containing the real content) and a "version" element which indicates the API version to use. Currently there is only "version: 1" available. In case a new feature is added to the API (and it required a backward incompatible API change) then the "version" attribute must be adjusted properly to use the feature.

Messages staying in the same version (along different CloudBees Jenkins Enterprise versions) are granted to be always compatible.

In next examples, the cli script is a simplification for the whole Jenkins CLI command which is:

java -jar jenkins-cli.jar -noKeyAuth -auth $user:$token -s $url $* | python -m json.tool

Where $user is the Jenkins user to perform the operations, $token is the access token and $url is the Jenkins root URL. jenkins-cli.jar must be downloaded from $url/jnlpJars/jenkins-cli.jar

All new commands provide in-line help with input examples. Help information can be accessed by cli help [command].

Teams

Use the teams command to:

  • Create or update a team (requires a JSON as input which contains the team definition, including Team Members).

  • Get the list of teams.

  • Get detailed information about a team.

Get teams

Returns the list of teams in CloudBees Jenkins Enterprise.

$> cli teams
{
    "data": [
        {
            "displayName": "A Team",
            "name": "a-team",
            "provisioningRecipe": "basic",
            "status": {
                "team": "READY"
            }
        }, {
            "displayName": "B Team",
            "name": "b-team",
            "provisioningRecipe": "java-web",
            "status": {
                "team": "READY"
            }
        }
    ],
    "version": "1"
}

Create or Update a Team

Use a JSON file to define a team and create or update based on it.

$> cat a-team.json
{
    "data": {
        "displayName": "A Team",
        "icon": {
            "color": "#7ac2d6",
            "name": "code"
        },
        "members": [
            {
                "id": "simon@acme.com",
                "roles": [
                    "TEAM_ADMIN"
                ]
            },
            {
                "id": "all-developers-group",
                "roles": [
                    "TEAM_MEMBER"
                ]
            }
        ],
        "provisioningRecipe": "java-web",
        "name": "a-team"
    },
    "version": "1"
}

$> cli teams a-team --put < a-team.json
{
    "data": {
        "id": "a-team",
        "message": "Team [a-team] created successfully",
        "status": "success"
    },
    "version": "1"
}
Note
The Team ID passed as argument and the ID inside the JSON file must be the same.

Get Team Details

To get more detailed information about a team, specify the team name as argument:

$> cli teams a-team
{
    "data": {
        "displayName": "A Team",
        "icon": {
            "color": "#7ac2d6",
            "name": "code"
        },
        "members": [
            {
                "id": "simon@acme.com",
                "roles": [
                    "TEAM_ADMIN"
                ]
            },
            {
                "id": "all-developers-group",
                "roles": [
                    "TEAM_GUEST"
                ]
            }
        ],
        "provisioningRecipe": "basic",
        "name": "a-team",
        "status": {
            "team": "READY"
        },
        "url": "http://acme.com/a-team/"
    },
    "version": "1"
}
Note
The argument is a Team ID (as returned in the "name" attribute in the listing call).

Team Members

Get Team Members

Retrieves the team members given a team name.

$> cli team-members a-team
{
    "data": [
        {
            "id": "simon@acme.com",
            "roles": [
                "TEAM_ADMIN"
            ]
        },
        {
            "id": "all-developers-group",
            "roles": [
                "TEAM_GUEST"
            ]
        }
    ],
    "version": "1"
}

Set Team Members

Use the --put option to set all members at once:

$> cat a-team-members.json
{
    "data": [
        {
            "id": "simon@acme.com",
            "roles": [
                "TEAM_ADMIN"
            ]
        },
        {
            "id": "all-developers-group",
            "roles": [
                "TEAM_GUEST"
            ]
        },
        {
            "id": "ada@acme.com",
            "roles": [
                "TEAM_GUEST"
            ]
        }
    ],
    "version": "1"
}
$> cli team-members a-team --put < a-team-members.json

Or the more granular way to add/update/delete only one member:

$> cli team-members a-team --add ada@acme.com --roles TEAM_GUEST
{
    "data": {
        "id": "a-team",
        "message": "Member [ada@acme.com] was added to the team",
        "status": "success"
    },
    "version": "1"
}

$> cli team-members a-team --update ada@acme.com --roles TEAM_MEMBER
{
    "data": {
        "id": "a-team",
        "message": "Member [ada@acme.com] was updated",
        "status": "success"
    },
    "version": "1"
}

$> cli team-members a-team --delete ada@acme.com
{
    "data": {
        "id": "a-team",
        "message": "Member [ada@acme.com] was removed from the team",
        "status": "success"
    },
    "version": "1"
}

Team Roles

New User Experience For CloudBees Jenkins Enterprise comes with a predefined set of roles which are automatically set for new Teams. However once the Team is created it is possible to customize the roles available for the Team.

Get Team Roles

Get available roles for a Team:

$> cli team-roles a-team
{
    "data": [
        {
            "defaultRole": false,
            "id": "TEAM_ADMIN",
            "name": "Team Admin"
        },
        {
            "defaultRole": true,
            "id": "TEAM_MEMBER",
            "name": "Team Member"
        },
        {
            "defaultRole": false,
            "id": "TEAM_GUEST",
            "name": "Team Guest"
        }
    ],
    "version": "1"
}

Set Team Roles

To set all Team roles (and the permissions for each of them) at once use the --put option:

$> cat a-team-roles.json
{
    "version": "1",
    "data": [{
        "name": "A new Role",
        "id": "NEW_ROLE",
        "defaultRole": true,
        "jenkinsInstancePermissions": [
            "hudson.model.Hudson.Read"
        ],
        "teamPermissions": [
            "hudson.model.Hudson.Read"
        ]
    },
    {
        "name": "Team Admin",
        "id": "TEAM_ADMIN",
        "defaultRole": false,
        "jenkinsInstancePermissions": [
            "hudson.model.Hudson.Administer"
        ],
        "teamPermissions": [
        ]
    }]
}

$> cli team-roles a-team --put < a-team-roles.json
{
    "data": {
        "id": "a-team",
        "message": "Team [a-team] was updated with the given list of roles",
        "status": "success"
    },
    "version": "1"
}
Note
The command will fail when using --put if the resulting roles set is breaking the team security, for example if there is a member assigned to a role that is not present in the new set of roles.

As noted in the examples, the team-roles command also allows to set role permissions when using --put, even when there is a specific command to manage permissions (team-permissions). This is done that way because it is a common use case to set roles and permissions at the same time in the same call, so there is no need to make two consecutive calls to two different endpoints.

To manage the permissions set of a given role (instead of all roles at once) use the team-permissions command (described in the next section).

As usual, the team-roles command also provides a more granular interface to operate on a single role. To add a new role use:

$> cli team-roles a-team --add MY_NEW_ROLE --display 'My New Role'
{
    "data": {
        "id": "a-team",
        "message": "Role [MY_NEW_ROLE] was added to the team",
        "status": "success"
    },
    "version": "1"
}

Then permissions can be set on that role using the team-permissions command.

What is the difference between jenkinsInstancePermissions and teamPermissions? See the next section for it.

Team Permissions

This endpoint manages the set of permissions that a role grants. There are two types of permissions, depending on the item they are set in the underlying Team Master:

  • Jenkins instance permissions: these permissions are granted at top level in the Team Master (they are usually global permissions, like Jenkins Admin or Nodes Admin). They are mapped in the jenkinsInstancePermissions attribute in JSON messages.

  • Team permissions: granted at Team Folder level, so they apply to Team Master items (Pipelines and possibly other item types under the Team Folder, like Agent Templates). They are mapped in the teamPermissions attribute in JSON messages.

Get Available Permissions

To get all the permissions available to be set on a role for a given Team. They can all be set at Jenkins instance or Team level:

$> cli team-permissions a-team
{
    "data": [
        "com.cloudbees.jenkins.plugin.metrics.views.Alerter.Mute",
        "com.cloudbees.jenkins.plugin.metrics.views.Alerter.View",
        "com.cloudbees.jenkins.support.SupportPlugin.DownloadBundle",
        "com.cloudbees.plugins.credentials.CredentialsProvider.Create",
        "com.cloudbees.plugins.credentials.CredentialsProvider.Delete",
        "com.cloudbees.plugins.credentials.CredentialsProvider.ManageDomains",
        "com.cloudbees.plugins.credentials.CredentialsProvider.Update",
        "com.cloudbees.plugins.credentials.CredentialsProvider.UseItem",
        "com.cloudbees.plugins.credentials.CredentialsProvider.UseOwn",
        "com.cloudbees.plugins.credentials.CredentialsProvider.View",
        "hudson.model.Computer.Build",
        "hudson.model.Computer.Configure",
        "hudson.model.Computer.Connect",
        "hudson.model.Computer.Create",
        [.. removed for docs clarity ..]
        "nectar.plugins.rbac.groups.Group.Configure",
        "nectar.plugins.rbac.groups.Group.Create",
        "nectar.plugins.rbac.groups.Group.Delete",
        "nectar.plugins.rbac.groups.Group.Manage",
        "nectar.plugins.rbac.groups.Group.View",
        "nectar.plugins.rbac.roles.Role.Filter",
        "nectar.plugins.rbac.roles.Role.View"
    ],
    "version": "1"
}

Get Permissions of a Role

To get detailed information about permissions on a given role:

$> cli team-permissions a-team TEAM_GUEST
{
    "data": {
        "jenkinsInstancePermissions": [
            "hudson.model.Hudson.Read"
        ],
        "role": "TEAM_GUEST",
        "teamPermissions": [
            "hudson.model.Item.Discover",
            "hudson.model.Item.Read",
            "hudson.model.Run.Artifacts",
            "hudson.model.View.Read"
        ]
    },
    "version": "1"
}

Set Permissions for a Role

To set all the permissions for a role at once:

$> cat a-team-guest-permissions.json
{
    "data": {
        "jenkinsInstancePermissions": [
            "hudson.model.Hudson.Read"
        ],
        "role": "TEAM_GUEST",
        "teamPermissions": [
            "hudson.model.Item.Discover",
            "hudson.model.Item.Read",
            "hudson.model.Run.Artifacts",
            "hudson.model.View.Read",
            "hudson.model.Item.Build"
        ]
    },
    "version": "1"
}

$> cli team-permissions a-team TEAM_GUEST --put < a-team-guest-permissions.json
{
    "data": {
        "id": "TEAM_GUEST",
        "message": "Permissions set correctly",
        "status": "success"
    },
    "version": "1"
}

And also the more granular arguments can be used:

$> cli team-permissions a-team TEAM_GUEST --add hudson.model.Item.Build --type team
{
    "data": {
        "id": "TEAM_GUEST",
        "message": "Permission added correctly",
        "status": "success"
    },
    "version": "1"
}

$> cli team-permissions a-team TEAM_GUEST --delete hudson.model.Item.Build --type team
{
    "data": {
        "id": "TEAM_GUEST",
        "message": "Permission deleted correctly",
        "status": "success"
    },
    "version": "1"
}
Note
The type option values are "team" or "jenkins" to add the permission at Team or Jenkins level respectively.

Team Creation Recipes

You will be able to use the output of the listing, to update them using --put. You are allowed to override or delete any recipe, including the predefined ones. The only exception is that you cannot delete the last recipe (because this would then prevent the creation of a Team, as the recipe is a required parameter).

Tip
Use the default attribute to mark a recipe as the first and default option in the UI. Only one default is expected (though it is not enforced: if you make many recipes default, the first one found will be set as default).

List all recipes

$> cli team-creation-recipes
{
  "version": "1",
  "data": [
    {
      "name": "basic",
      "displayName": "Basic",
      "description": "The minimalistic setup.",
      "plugins": [
        ...
        "workflow-aggregator",
        "workflow-cps-checkpoint"
      ],
      "default": true
    },
    {
      "name": "java-web",
      "displayName": "Java & Web Development",
      "description": "The essential tools to build, release and deploy Java Web applications including integration with Maven, Gradle and Node JS.",
      "plugins": [
        ...
        "pipeline-maven",
        "tasks",
        "warnings"
      ],
      "default": false
    },
    {
      "name": "with-catalog",
      "displayName": "With a plugin catalog",
      "description": "Setup integrating a plugin catalog",
      "pluginCatalog": "one-plugin-catalog",
      "plugins": [
        ...
        "pipeline-maven",
        "tasks",
        "warnings"
      ],
      "default": false
    }
  ]
}

Add, update or remove recipes

The simplest way to do this is to redirect the output of the recipes listing to a file, edit it, then pass it as input to this command.

$> cli team-creation-recipes --put < all-recipes.json
{
  "version": "1",
  "data": {
    "id": null,
    "message": "Recipes list updated successfully",
    "status": "success"
  }
}

Delete a specific recipe

$> cli team-creation-recipes --delete java-web
{
  "version": "1",
  "data": {
    "id": "java-web",
    "message": "Recipe [java-web] deleted",
    "status": "success"
  }
}

1. this is mostly dependent on the infrastructure, but it is generally expected to take less than one minute.