The guide describes the features of Red Hat OpenShift.io. It also contains information about potential problems users may encounter while using the software. Where possible, workarounds are described for identified issues.

Before you start

1. Introduction to Red Hat OpenShift.io

Red Hat Developer Program offers a Software as a Service (SaaS) product for developers called Red Hat OpenShift.io to meet your software development requirements.

This section introduces Red Hat OpenShift.io and provides an overview of the main features of the product. Read it to understand the benefits of using OpenShift.io and to learn about how organizations and developers can use it for their everyday tasks.

1.1. Red Hat OpenShift.io overview

Red Hat OpenShift.io is a highly collaborative open-source, web-based application life cycle management (ALM) solution. It is a next-generation product for developers to manage the development life cycle with one efficient tool. It enables you to plan, create, and deploy hybrid cloud services. It utilizes many open source projects like fabric8, Eclipse Che, and OpenShift Online

1.1.1. Features

OpenShift.io offers features to seamlessly manage end-to-end application development. It provides an integrated approach to DevOps with all the tools necessary to analyze, plan, create, and deploy services. Members of distributed teams can use it to perform the following tasks without leaving the browser window:

Project management:

  • Project planning and issue tracking using your choice of Agile methodology.

  • Automating project releases.

  • Minimize effort on building and maintaining a development tool chain.

Project development:

  • Creating containerized development, testing, and staging environments hosted on OpenShift Online.

  • Coding, editing and debugging using an integrated development environment based on Eclipse Che, which provides a workspace for developing and managing your application.

  • Development in this context-aware environment provides the appropriate context for the developer and project, such as which branch, repository, language, and files are referenced.

  • Interacting with integrated GitHub repositories.

  • Compiling and reviewing code in Pull Requests as required.

  • Use the QuickStart wizards to create basic applications with their own new repo on GitHub, integrated Jenkins pipelines plugins, and a related new OpenShift project.

  • Using migration wizards to migrate legacy J2EE applications to the cloud.

Deployment and testing:

  • Building, testing, deploying, and monitoring codebases using Continuous Integration pipelines that can be tailored to the requirements of a team - you can have simple automated build pipelines or add manual promotions.

  • Deploying applications packaged as a set of containers to OpenShift, which powers the underlying services such as the Eclipse Che workspaces and Pipelines.

  • Using integrated but customizable Jenkins build pipelines to facilitate rapid testing and environment promotion, reducing your build and maintenance efforts.

Analysis and recommendations:

  • Use the full-stack analysis feature on the software components in your application to identify potential security issues in your source code and get suggestions on safer alternative components to use instead.

  • Use the self-learning analytics engine to improve the code quality and make data-based choices. The engine scans community libraries, security vulnerabilities, and other GitHub metrics to provide useful real-time assistance for developers that learns and improves over time.

See also the following related Red Hat resources related to the Red Hat Developer Program:

2. Getting support

The OpenShift.io team love to get feedback from our users. Tell us what you like, what you hate, what you wish you could do, what you wish the service would stop doing, and anything else that you think we should know as we work on improving OpenShift.io.

2.1. Asking questions about the product

The OpenShift.io support chat channel is the best way to ask questions or get immediate support for OpenShift.io at any time. We encourage users to ask us questions and get immediate answers and assistance rather than spend their time debugging or troubleshooting problems themselves.

If you don’t already have a MatterMost account:

  1. Navigate to https://chat.openshift.io and click Create one now.

    Create an account
  2. Add your details and click Create Account to register.

  3. In your email inbox, click the Verify Email link.

    Verify email
  4. Sign in when prompted. When asked, select Developers.

    Select team
  5. MatterMost offers an optional tutorial for new users, which you can skip. Click Skip tutorial to continue.

    Skip tutorial
  6. You are redirected to the #openshiftio channel.

    Main view
  7. Ask a specific person your question or start with @here to tag everyone present in the channel.

In the future, navigate to https://chat.openshift.io to view the OpenShift.io MatterMost channel.

If you prefer to use IRC, the OpenShift.io team is also available in the #openshiftio channel on Freenode.

2.2. Send us feedback about the product

To give the OpenShift.io team feedback, navigate to create an issue and send us a description of the problem with the necessary details, including screenshots if necessary. You can also search for related issues at this link. When logged, the OpenShift.io team triages and adds tags and other information to your issue.

If you prefer to send us feedback via email, send us the details at openshiftio@redhat.com.

2.3. Send us feedback about the documentation

The documentation team welcomes all feedback or requests for information that is helpful to you but isn’t covered.

  • Is there anything we can do to improve the documentation?

  • Was a part of the documentation not useful for you?

  • Is there anything we did not document that you want to do with OpenShift.io?

Create an issue to send us your feedback.

3. Accessing Red Hat OpenShift.io

This section explains how to register and gain access to Red Hat OpenShift.io. It also outlines how to log in to and log out of the service.

3.1. Signing up for the Red Hat Developers Program

To start using Red Hat OpenShift.io, create a new Red Hat Developers (RHD) account or use an existing RHD or social media account.

  1. Navigate to Red Hat OpenShift.io.

  2. Click Sign Up. You can register using an existing social or Red Hat account.

    • To register a new Red Hat account:

      1. At the Red Hat OpenShift.io Developer page, click Register.

      2. Enter your name, email address, company, and password in the appropriate fields.

      3. Select the terms and conditions check boxes.

      4. Click Create my account.

      5. Verify your email address to complete registration.

    • To register using your existing Red Hat account or a social account from services such as JBoss Developer, GitHub, Stack Overflow, LinkedIn, Twitter, Facebook, Google, or Microsoft:

      1. Click the appropriate social account button.

      2. Add your login credentials for the selected service and authorize the creation of the account.

3.2. Logging into Red Hat OpenShift.io

When you sign up to use OpenShift.io, you are given an OpenShift Online account with enough resources to run a basic stage and run environment, pipelines, and an Eclipse Che development workspace.
Prerequisites
Procedure
  1. Navigate to the Red Hat OpenShift.io website in a browser window.

  2. Click Log In at the top of the OpenShift.io main page.

  3. Log in either manually (with your Red Hat Developers account) or using a social account:

    1. Log in using your Red Hat account:

      1. Enter your email address or Red Hat Developers Login ID and password.

      2. Click Log In.

    2. Log in using a social account:

      1. Click the appropriate social account button from the listed options.

      2. Follow the instructions to allow the social account to log in.

      3. If asked, add information about yourself on the Additional Action Required page. If the provided email address already has an account, an option to link your social account with your Red Hat Developers account is available. An email arrives in the account to confirm linking the two accounts.

  4. Select the check boxes to indicate agreement with the terms and conditions if required and click Submit.

3.3. Logging out of Red Hat OpenShift.io

Prerequisites
  • Ensure that you have logged in to the Red Hat OpenShift.io website.

Procedure
  1. Click your name in the top right corner of the application.

  2. In the drop-down menu, click the Log Out option.

Getting Started with OpenShift.io

4. Changing user preferences

After logging in to OpenShift.io, you can change your user preferences in the Profile section.

4.1. Editing your profile

In the OpenShift.io Profile view, use the following steps to change your personal settings:

  1. Navigate to your Profile view:

    1. Click your name on the top right corner of the screen.

    2. Click Profile from the displayed options.

      Profile menu button
  2. In the Profile screen, click Edit Profile to edit your profile.

    Edit profile button
  3. The dialogue lets you edit your Name, Email, Company, and Password, add your personal URL and Bio, and Reset Environment.

    You can opt to keep your email address private from other users in OpenShift.io by selecting the Private option. The default option is Public.
    Edit profile
  4. When ready, click Update at the bottom of the dialogue to save your changes.

You have now changed your profile settings in OpenShift.io.

4.2. Changing your password

In the OpenShift.io dashboard view, use the following steps to change your password:

  1. Navigate to your Profile view:

    1. Click your name on the top right corner of the screen.

    2. Click Profile from the displayed options.

      Profile menu button
  2. In the Profile screen, click Edit Profile to edit your profile.

  3. At the bottom of the edit profile screen, click Change password.

    Edit profile
  4. You are redirected to the Red Hat Developers Change Password page. Add your current password and new password to the appropriate fields and click SAVE to save the changes.

You have now successfully changed your OpenShift.io password.

4.3. Cleaning your OpenShift Online account

OpenShift.io generates artifacts within five projects (Kubernetes namespaces) in OpenShift Online. See viewing projects in OpenShift Online for details.

This section describes how to reset your OpenShift Online account, which can serve two purposes:

Freeing resources used by applications

After you create a quickstart application, the limited resources available in the OpenShift Online Free Tier are nearly exhausted. You can reset your OpenShift.io and Openshift Online account resources to start afresh.

General troubleshooting

If your OpenShift.io environment is in a state where you find it difficult or impossible to move forward, you can reset your environment to start afresh.

Procedure

  1. On your OpenShift.io home page, click your name in the top right corner of the screen.

    1. In the drop-down options, click Profile.

    2. On the profile page, click Edit Profile.

  2. In the edit profile page, click Reset Environment.

    Edit profile
  3. A warning page appears with a summary of your OpenShift.io account. Click Erase my OpenShift.io Environment.

    Erase My OpenShift.io environment
  4. In the dialog box, add your OpenShift.io user name and click I understand my actions - erase my environment.

    Confirm
  5. After the environment is successfully erased, the success page displays:

    Success

After completing these steps, your OpenShift.io and OpenShift Online account resources are reset and ready for use with a new project.

4.4. Adding a GitHub organization

  1. In a new browser tab, navigate to https://github.com/settings/organizations

  2. To create a new organization in GitHub:

    1. Click New organization to create a new organization.

    2. Add a name and email address for your new organization.

      New organization fields

    3. Under Choose your plan, select Free.

    4. Click Create organization.

    5. In the Invite organization members screen, add users or click Finish to skip this step and create the organization. The new organization details now display.

  3. Now navigate to https://github.com/settings/applications

  4. Click Openshift.io from the list of applications.

  5. In the details page for the application, your new organization is listed under Organization access. Click Grant to give the new organization access.

  6. Return to the OpenShift.io tab in your browser.

  7. Navigate to your Settings view:

    1. Click your name on the top right corner of the screen.

    2. Click Settings from the displayed options.

      Profile menu button
  8. Under Connected Accounts, click the refresh icon for your GitHub account.

    Refresh github
  9. After the reloaded OpenShift.io screen loads, your new organization is added.

To use the new organization, create a new project and in the Organization drop-down menu, your new organization is listed.

4.5. Opting in to features

In the OpenShift.io dashboard view, use the following steps to opt in or out of features:

  1. Navigate to your Settings view:

    1. Click your name on the top right corner of the screen.

    2. Click Settings from the displayed options.

      Profile menu button
  2. In the Settings page, click Features Opt-in.

    Features Opt In
  3. Select the appropriate option from the list. The Production Only Features option is recommended for users who only want the stable OpenShift.io features.

    Opt in features

    The change is applied to your profile. The following message displays to confirm that you have opted in to the selected features:

    Profile updated

You have now opted in to the desired features in OpenShift.io.

4.6. Viewing resource usage

An OpenShift.io account with OpenShift Online provides two pods for your projects. To view how many of these resources are currently used in OpenShift.io, navigate to the Resources page as follows:

  1. Click your username in the upper right corner of the OpenShift.io page and click Settings.

    Profile menu button
  2. In the menu options, click Resources.

    Settings > Resources

In the displayed resources page, you can see how much of the available resources are used so far.

If you have not added any projects to your OpenShift.io account, the page shows all resources as available:

Resources all available

If you have created one project, which is not pushed to Run yet, the page shows that some of the resources for Stage are in use.

Resources half

After you create two projects, the two pods allocated to an OpenShift Online account have been used. Use this page to check if you have resources remaining because additional builds will fail if the required resources are not available. See resetting your environment to reclaim all these resources.

4.7. Reviewing detailed resource information in OpenShift Online

After creating or adding a project to OpenShift.io, you can see more detailed resource usage in OpenShift Online as follows:

  1. In a new browser tab, navigate to the OpenShift Online console at console.starter-us-east-2.openshift.com.

  1. From the list of projects at the right side of the page, click username-run to see the resources used for the Run environment or username-stage to see the resources for the Stage environment.

    Select the Run Project
  2. Click Applications and then select Pods in the displayed submenu.

    Application Pods
  3. The Pods page lists your Hello World project pod. Click the project name to see the resource information for the project.

    Hello World Project Pod
  4. The Details page lists the Status of the pod and the container resource information:

    Resources

    Use this page to review the memory usage for your OpenShift.io project.

5. Working with spaces

5.1. About spaces

A space is the first thing a user creates in OpenShift.io. All other elements are created within a space to organize them for each project. A space allows you to plan your development work using work items and iterations, assign work items to collaborators within your team, and create software applications within it.

Each codebase, iteration, work item, and collaborator is attached to a space. As an example, each space can contain multiple codebases, work items tracking work to be done in a project, collaborators working on their assigned work items, and iterations to track when the work items are to be done.

5.2. Creating a new space

In OpenShift.io, the first step for any new project is to create a new space.

You can then add collaborators, track your work using work items and iterations, and create or import codebases within the space. Each space must have a unique name.

Prerequisites

Procedure

Create a new space as follows:

  1. In the OpenShift.io home page, click Create a space.

    Create your first space

    If your account has an existing space, click + to create an additional space instead:

    Second space
  2. If this is the first space you are creating with your OpenShift.io account, a message about connecting to GitHub appears. To connect your GitHub account to OpenShift.io:

    1. Click Connect to GitHub.

      GitHub Disconnected
    2. If your browser session is already logged in to a GitHub account, OpenShift.io uses it for the GitHub connection step. If not, you are prompted to add your GitHub credentials to connect the account to OpenShift.io.

      Connect to GitHub
  3. When the accounts are connected, the OpenShift.io home page view displays. Click Create a space again.

  4. Use the Development Process drop-down list to select a template for your new space. You can select Scenario Driven Development or the Scrum template. For this example, keep the default option for this field.

    The Development Process you select while creating your space determines the guided work item type hierarchy in planner and the available work item types to plan your development work.
  5. In the dialog box, type a unique name for your space and click Ok.

    Create new space

You have now created your first space.

5.3. Deleting an existing space

If an OpenShift.io space is no longer required, delete it as follows:

When deleted, the space and all its contents (work items, codebases, workspaces, etc.) are also permanently deleted.
  1. On your Red Hat OpenShift.io home page, click your user name in the upper-left corner of the screen.

  2. On the drop-down list, click View all spaces.

  3. Click the trash can icon (delete), the Remove Space dialog box displays asking for confirmation.

  4. Click Remove to confirm and delete your space.

6. Working with areas

6.1. About areas

Areas can organize related work items into groups to distinguish between different types or functionalities that are worked on within a space.

A space can include multiple areas. As an example, your space represents your software project, and each area tracks components attached to the space.

Each area can have child areas which represent the sub-components for your software project.

6.2. Creating a new area

You can create a new child area to group together related work items by type or functionality. When you create a new space, OpenShift.io automatically creates a root area with the same name. Each additional area within the space is created as a child of the root area or another existing area in the space.

Prerequisites
Procedure
  1. From your OpenShift.io dashboard, click the name of a space to view its dashboard.

  2. At the top of the page, click the Equalizer tab (equalizer) to display a list of areas in your space.

  3. In the top right corner of the Areas view, click Add Areas.

    Add areas button
  4. In the Add New Area dialog box, add a name for your new area and a parent area.

    Add new are dialog
  5. Click Create to create the new child area.

  6. To view your new area, click the expand icon for your space name. Your new area is listed as a child of the root area, which shares a name with the space.

    See new area

6.3. Assigning an area to a work item

You can group work items by type or functionality by assigning relevant areas to the work items as follows:

Prerequisites
Procedure
  1. Click the Plan tab to view a list of work items for your space.

  2. Click on a work item to view its details in the preview.

  3. Click the Area field to view a list of areas to assign to the space. By default, your root area is assigned to a new work item.

    Assign area
  4. Select one of the existing areas to assign to your work item.

  5. Click the check box to confirm the name of the area.

Your work item is now assigned to the selected area.

7. Working with collaborators

7.1. About collaborators

Collaborators are members assigned to particular work items within a space. They are assigned tasks for the development project which are tracked using work items. You can add collaborators to your space and then assign the relevant work items to them.

7.2. Adding collaborators

You can add other OpenShift.io users as collaborators to your space and then assign work items to each person.

Prerequisites
  • Create a new space or select an existing space.

  • Ensure that the user you want to add as a collaborator has an OpenShift.io account.

Procedure
  1. From your OpenShift.io dashboard, click the name of a space to view its dashboard.

  2. Click the Equalizer tab (equalizer) at the top of the screen.

  3. Click Collaborators.

    Collaborators button
  4. Click Add Collaborators in the top right corner.

    Add collaborators button
  5. In the Add collaborators dialog box, click Select and type a name in the text box to search for a user.

    Add collaboraters dialog
  6. From the displayed results, select the name of one or multiple users to add as collaborators for your space.

  7. Click Add to add the selected users as collaborators.

The Collaborators page now includes the users you selected as collaborators for your space.

7.3. Viewing and changing collaborators

After adding collaborators, you can view their details or remove them from your space.

Prerequisites
Procedure
  1. Click the Equalizer tab (equalizer) at the top of the screen.

  2. Click Collaborators.

    Collaborators button
  3. From the displayed list of collaborators on the Collaborators page, click the three dots next to the collaborator name.

    Edit collaborators
  4. Either:

    • Select View user to view the collaborator details.

    • Select Remove from space to remove them from the space.

7.4. Assigning a collaborator

After adding collaborators to your space, you can assign work items to them:

Prerequisites
Procedure
  1. Click the Plan tab to view a list of work items for your space.

  2. Click on a work item to view its details in the preview.

  3. In the Assignees field, click Add Assignee to see the list of collaborators you can assign the work item to.

    Assign collaborator
  4. Select from the displayed list or type the name of a collaborator in your space to assign them to this work item. The check mark indicates that a collaborator has been assigned. Click X to close the dialog window.

    Assign collaborator check mark

The work item is now assigned to the selected collaborator.

8. Working with work items

8.1. About work items

Work items are measurable units of work within a space that can be tracked. They are captured representations of work, assigned to a team member. Work items track data such as user stories, scenarios, tasks, and bugs.

OpenShift.io planner is a task or work item tracker to plan and execute your project work.

The planner includes a set of predefined templates based on common development methodologies such as Scrum and Scenario Driven Development. These templates determine the structure and features of the included work item types and states that are available for a space.

Work items can be grouped and categorized into various work item types depending on the template you select for a space. In addition, you can associate the work items to Iterations and sprints to track progress and plan work.

This enables you to plan, execute, and track your development work based on the project management methodology you adopt.

8.2. Creating a new work item

The space template you select determines the structure of the guided work item type hierarchy, the work item types available for a space, and their features.

The fastest way to create work items in the planner is to use the quick-add option.

Prerequisites
Procedure
  1. Select the Plan tab at the top of the page to view the planner. The default Backlog view displays the top level work item type group for your space.

    The space template determines the available work item types in planner.
  2. In the Add Work Item pane, select the required work item type from the work item type drop-down list.

    Create Work Item
  3. Specify an appropriate title for the work item in the Work Item Title field.

  4. Click Add or press Enter to create the work item. Alternatively, to add further details to the work item, click Add and open to create the work item and see the detailed view for the work item.

    First Work Item

The planner provides guided work item type hierarchies based on established development methodologies such as Scenario Driven Development and Scrum. See using the work item type hierarchy for information about planning your development work by creating appropriate work items,and executing them according to these development methodologies.

8.3. Using the guided work item type hierarchy to create work items

The Development Process you select while creating your space determines the guided work item type hierarchy and the available work item types in planner. The Scrum and Scenario Driven Development guided hierarchies help you to easily plan your development work according to established development processes and execute it efficiently.

8.3.1. Using the Scenario Driven Development guided hierarchy

Scenario driven development is an agile development methodology focused on real-world problems, or scenarios, described in the language and from the viewpoint of the user. Scenarios deliver particular value propositions and are realized through experiences.

The Development Process you select while creating your space determines the guided work item type hierarchy, the available work item types, and the available states of the work item in planner.

Use the scenario driven guided hierarchy to create work items as follows:

Prerequisites
  • Create a space using Scenario Driven Development as your Development Process.

Procedure
  1. Select the Plan tab at the top of the page to view the planner. The default Backlog view displays the top level work item type group, that is Scenarios, for your space.

  2. Select the Show Tree check box to see the work items in a tree view. The tree view allows you to quickly add work items according to the guided hierarchy using the quick-add and the in-line add options.

  3. Based on the vision statement for the product, use the quick-add option to create high level planning oriented work items, as follows:

    1. In the Add Work Item pane, select the required high level work item type from the work item type drop-down list. As per the scenario driven development process, you can create Scenario, Fundamental, or Papercuts type of work items, which are tracked under the Scenarios work item type group.

      Select Scenarios
    2. Specify an appropriate title for the work item in the Work Item Title field.

    3. Press Enter to create the work item. Alternatively, to create the work item and see the detailed view for the work item, click Add and open.

  4. Create child work items for the Scenarios using the in-line add option as follows:

    1. In the work item list, click the (+) icon adjacent to the work item for which you want to add child work items. The in-line Add Child Work Item pane is displayed below the work item.

    2. From the work item type drop-down list, select the required child work item type. As per the scenario driven hierarchy, you can create Experience, or Value Proposition type of child work items. These work items are tracked under the Experiences work item type group.

      Select Experiences
    3. Add a title to the work item and press Enter to create the work item.

  5. Similarly, use the in-line add option to create execution oriented child work item types for the Experiences. The scenario driven hierarchy enables you to create Feature or Bug to track such work items.

    Select Requirements
  6. Use the in-line add option again to further break down the execution oriented work items. The scenario driven template gives you the option to create action oriented Task or Bug type of work items.

    Select Tasks

    All the execution oriented, Feature, Task, and Bug work item types are tracked under the Requirements work item type group.

For more information see:

8.3.2. Using the Scrum guided hierarchy

Scrum is an iterative and incremental agile software development framework for managing product development.

The Development Process you select while creating your space determines the guided work item type hierarchy, the available work item types, and the available states of the work item in planner.

Use the scrum guided hierarchy to create work items as follows:

Prerequisites
Procedure
  1. Select the Plan tab at the top of the page to view the planner. The default Backlog view displays the top level work item type group, that is Epics, for your space.

  2. Select the Show Tree check box to see the work items in a tree view. The tree view allows you to quickly add work items according to the guided hierarchy using the quick-add and in-line add options.

  3. Based on the vision statement for the product, use the quick-add option to create a high level, planning oriented Epic, as follows:

    1. In the Add Work Item pane, specify an appropriate title for the Epic in the Work Item Title field.

      Create Epic
    2. Press Enter to create the work item. Alternatively, to create the work item and see the detailed view for the work item, click Add and open.

  4. Create a child Feature for the Epic using the in-line add option as follows:

    1. In the work item list, click the (+) icon adjacent to the Epic for which you want to add a child Feature.

      Inline Add

      The in-line Add Child Work Item pane is displayed below it.

      Add Feature
    2. Add a title to the Feature and press Enter to create the feature.

  5. Similarly, for the Feature, use the in-line add option to create execution oriented child Product Backlog Item or Bug type work items.

    PBI or Bug drop-down
  6. Use the in-line add option again to further break down the Product Backlog Item into action oriented, more granular Product Backlog Item type or Task type of work items.

    Granular PBI or Tasks

    All the execution oriented, Product Backlog Item, Task, and Bug work item types are tracked under the Backlog items work item type group.

For more information see:

8.4. Viewing work items

The planner provides an interface to plan and execute your development work by creating work items, grouping them into work item type groups for efficient planning, and associating them with iterations for effective execution.

The left pane of the planner displays:

  • The work item type groups determined by the space template

  • Your iterations outlining your development work

  • Your saved filters

Left Pane

This pane can be hidden or displayed using the Hide Panel or Show Panel icon as required.

The right pane displays the list of work items in your space that can be viewed either using the tree view or the flat view.

Right Pane
  1. By default, closed work items are not listed in the work item list. Select the Show Completed check box to see the closed work items.

  2. Use the gear icon next to the Add and Open button to select the attributes you want to see for your list of work items.

    Display Work Item Attributes

8.4.1. Tree view of work items

The tree view is the default view of the planner. It displays the list of work items along with their parent and child work item links in a hierarchical structure, providing you the context of the work item in relation to the broader project goals.

It ensures your features and tasks have appropriate parent experiences or value propositions associated with them, limiting the chance of feature creep in your development work. This enables you to plan and take up work items focused on delivering actual customer value.

The tree view helps you create appropriate child work items based on the guided work item type planning hierarchy, aiding better planning, prioritizing, and execution.

You can view, track, and plan your work items along with their parent-child links using the tree view as follows:

Ensure that the Show Tree check box is selected.
  1. Click Plan and then Backlog. The Scenarios for your space are displayed by default in a tree hierarchy.

  2. Expand the work items to see the child Experiences and Requirements type work items associated to them.

    Scenario with Child Work Items
  3. In the left pane, select Experiences to see the Experiences and Value Propositions. They are highlighted in bold and display both the associated parent Scenarios and child Requirements.

    Experience with Parent and Child Work Items
  4. Similarly, select Requirements to see the Features and Bugs. They are highlighted in bold and display their parent Scenarios and Experiences and their child Tasks.

    Requirement with Parent and Child Work Items

8.4.2. Flat view of work items

The flat list view is useful to track your work items based on their work item type groups. Depending on the selection of the work item type groups in the left pane of the planner, it displays the Scenarios, Experiences, or Requirements for your space.

It does not display the hierarchical parent-child links for the work items and focuses only on the selected work item type group. This helps you plan your Scenarios and Experiences or assign your Requirements to appropriate Iterations.

You can track a particular work item type group using the flat list as follows:

Ensure that the Show Tree check box is cleared to see the flat view.
  1. Click Plan and then Backlog. The Scenarios for your space are displayed by default in a tree hierarchy.

  2. Clear the Show Tree check box to see all your Scenarios in a flat view.

    Scenarios Flat View
  3. In the left pane, select Experiences or Requirements to see the Experiences or Requirements for your space, respectively.

    Experiences Flat View

8.4.3. Ordering work items

The planner work items can be moved higher or lower the list depending on their priority or the order of execution.

Click Plan to view the planner work item list. You can move a work item higher or lower the list as follows:

  1. Move the mouse pointer over the work item you want to reorder to highlight it.

  2. Move the mouse pointer over the vertical blue dotted line to the left of the selected work item, the pointer changes to the move-cursor (wi move cursor).

  3. Use the move-cursor to drag the work item to the required position in the list.

    Reorder Work Items
In the tree view, only work items which are on the same level in the tree hierarchy can be moved.

8.4.4. Filtering work items

You can filter your work item list in the planner as follows:

  1. Click Plan and then Backlog to see a list of your work items for the space.

  2. Click the Select drop-down list to select a filter type. You can filter work items by Assignee, Creator, Area, Workitem type, State, Label and Title. The drop-down next to the Select drop-down auto-populates options based on the selected filter type.

    Select Filter
  3. Click the Filter by filter type drop-down to see a list of valid options for the selected filter type.

    For example, in the Select drop-down list, if you select State as your filter type, the Filter by state drop-down displays all the possible states by which you can filter the work item such as, new, open, in progress, resolved, and closed.

    Filter Type Options
  4. Select the appropriate option to filter the work items and see the filtered list.

  5. Similarly, add multiple filters successively to further refine your work item list. The applied filters are displayed at the top of the filtered work item list. For example, you can see all the open bugs in your space by adding the state: open and the workitemtype: Bug filters successively.

    Multiple Filters
  6. If you are not satisfied with the filters, click x next to the filter type to clear that filter, or use the Clear all filters to clear all the filters applied to the work item list.

  7. After you are satisfied with the applied filters, click Save and add a name to the filter to save the filter for future use. In the above example, save the multiple filters you added as Open Bugs to track all your open bugs in the future. The filter Open Bugs is added to My Filters.

    My Filters
  8. You can modify an existing filter as follows:

    1. Select the filter on the left pane to see the filtered work item list.

    2. Add another filter or delete an existing filter as required and save the filter with a new name. In the above example, select the Open bugs filter and add the filter Assignee: your username to see open bugs assigned to you. Save this filter as Open bugs assigned to me for future use.

      Modify Filter
  9. To delete an existing filter, in the left pane, use the options (kabob) icon adjoining the filter to delete it.

8.5. Modifying a work item

After you create a new work item the planner provides you the option to preview your work item or see a detailed view of the work item.

You can use preview or the detailed view of your work item to modify your work item as required.

  • Preview: Click the title of a work item to preview the work item on the right of your screen.

    Work Item Preview
  • Detailed view: Click the Detailed view icon (Detailed View Icon)next to the work item to see the detailed view of the work item.

    Work Item Detailed View

You can make the following modifications to the work item, in the preview or the detailed view, to facilitate tracking and execution of the work item:

Before closing the preview or detailed view ensure that all your changes are individually saved.

8.5.1. Tracking the state of a work item

You can set the state for each of your work items enabling you to track the status of your work item from creation to completion.

The Development Process you select while creating your space determines the guided work item type hierarchy, the available work item types, and the available states of the work item in planner.

For this example, select the scenario driven Development Process.

By default, a freshly created work item is assigned the new state. You can track and update the status of work items as you progress through your task list as follows:

  1. Click the new drop-down list to see a list of states for the work item. You have the following options: open, in progress, resolved and closed.

    Work Item state
    The Scrum template provides you the following options: New, In-Progress, Done, Removed.
  2. Select the appropriate state based on the completion level of your work item. The state for the work item gets updated.

By default, closed work items are not listed in the work item list. Select the Show Completed checkbox to see the closed work items.

8.5.2. Editing the work item title

You can modify the title of your work item after it is created as follows:

  1. Click the title of the work item to modify it.

    Edit Work Item Title
  2. Make your changes and press Enter to save the change.

8.5.3. Assigning the work item

You can assign a work item to any of the collaborators added to your space.

By default, the Assignees field for a new work item displays Unassigned.

To assign your work item to a collaborator:

  1. In the Assignees field, click Add Assignee to see the list of collaborators you can assign the work item to. The list of available collaborators for a space is set by the administrator for a space.

  2. Select the assignees you wish to assign the work item to and click x to save the selection.

    Assigning Work Items

8.5.4. Associating a work item with an area

You can allocate a work item to a particular area to group it by functionality or type.

By default, the name of your space is set as the root area for a work item.

To assign a new area for your work item:

  1. In the Area field, click the root area to see the areas you can associate the work item with. The list of available areas for a space is set by the administrator for the space.

    Work Item-Area Association
  2. Select the required area and click to save the change.

8.5.5. Associating a work item with an iteration

You can associate work items with relevant iterations based on your order of execution.

By default, the name of your space is set as the root iteration for a work item.

To associate a work item with a relevant iteration:

  1. In the Iteration field, click the root iteration to see the iterations you can associate the work item with.

    Work Item-Iteration Association
  2. Select the iteration in which the work item is to be completed and click to save the change.

8.5.6. Adding and assigning labels to a work item

You can use labels to categorize and group work items as required.

Assign existing labels to your work items as follows:

  1. In the Labels field, click Add label to see the available labels in your space.

  2. Select the suitable labels and click x to assign the labels to the work item.

    Assign Labels

Add and assign new labels as follows:

  1. In the Labels field, click Add label to see the available labels in your space.

  2. At the bottom of the Add label list, click Create new label to add new labels to the work item.

  3. Optionally, click the default color displayed for the label to see a list of colors you can assign to the label and select the color you want to assign your label.

  4. Add an appropriate name to the label and click to save the label and add it to the list.

    Add Labels
  5. Select the label and click x to assign the label to the work item.

  1. After the labels are created for a work item they are available for all the work items in the space.

  2. You can assign multiple relevant labels to a work item.

8.5.7. Adding description to a work item

You can describe the details for your work item as follows:

  1. In the Description field, click in the text box to add description for the work item. Use the Preview tab to see the rendered markdown for your description.

    In addition to the standard markdown syntax, refer to these extensions for more information about the syntax.
    Markdown Description
  2. If you are satisfied, click to save the description.

    Description
Click the pencil icon to edit a saved description.

You can see existing links or create links to other work items establishing relations between them as follows:

  1. Expand the Links option to see the work items linked to this work item.

  2. Click Create Link to create new links to work items.

  3. Use the Select Link Type drop-down list to select the appropriate relationship between two work items. You have the following options: blocks, relates to, parent of, blocked by, is related to, child of.

    Linking Work Items
  4. In the Search for work items field, type the title or the ID of the required work item and select the work item.

  5. Click Link to save the relationship.

The linked work item is now listed under Links.

8.5.9. Adding comments to a work item

A team collaborating on a work item can add comments regarding the work item as follows:

  1. In the Add a new comment field, add your comment. Use the Preview tab to see the rendered markdown for your comment.

    In addition to the standard markdown syntax, refer to these extensions for more information about the syntax.
    Markdown Comment
  2. Click to submit your comment.

    Comment
  • Use the pencil icon to edit a submitted comment.

  • Use the kebab menu adjoining the comment to delete the comment.

9. Working with iterations

9.1. About iterations

Iterations are development cycles in the context of incremental development processes. Use iterations to prioritize work items and to implement them within a development cycle. When used with Scrum, iterations can be utilized to model sprints.

You can use the planner to map your work items to iterations and plan your work based on your project requirements. It enables you to set time-specific goals by grouping priority work items into a single development cycle. It also helps you track your progress for each iteration and compare it with past iterations and associated work items.

9.2. Creating a new iteration

Add iterations to your space to plan and organize your work items. Click Plan to view and modify existing iterations and to add new iterations.

Prerequisites
Procedure
  1. Click Plan to view the Planner.

  2. In the left pane, click Add an Iteration + next to the Iterations field. The Create Iteration window is displayed.

    Create Iteration
  3. Enter a Name for your new iteration.

  4. Optionally, create a parent link to another iteration by selecting the parent iteration from the Parent Iteration drop-down list. By default, the name of your space is set as the parent iteration.

  5. Add a Description for the new iteration.

  6. Add a Start Date and End Date for your new iteration.

  7. The iteration automatically becomes Active if the current date falls within the start and end date range. Alternatively, if required, toggle the Force Active switch to ON to force start the iteration. NOTE: You can have multiple iterations active at the same time.

  8. Click Create to create the new iteration.

Your new iteration appears under Iterations in the left pane. It is tagged as Active if the current date falls within the start and end date range or if you force-activated it.

Test Iteration

9.3. Associating a work item with an iteration

You can associate work items with relevant iterations based on your order of execution.

By default, the name of your space is set as the root iteration for a work item.

To associate a work item with a relevant iteration:

  1. In the Iteration field, click the root iteration to see the iterations you can associate the work item with.

    Work Item-Iteration Association
  2. Select the iteration in which the work item is to be completed and click to save the change.

9.4. Using an iteration

Use iterations to prioritize work items slated for execution in the development cycle.

  1. After you create an iteration and associate work items to the iteration, select the iteration to display the associated work items.

    Only execution work item types such as Feature, Task and Bug are displayed in the iteration view. You can use the tree view to see the parent Scenarios or Experiences linked to the work items in the iteration.
    Iteration View
  2. You can use the Add Work Item pane to further add new work items to the iteration.

  3. To modify the iteration click the options (kabob) icon next to the iteration and use:

    • Edit iteration name to see the Update Iteration screen and change the iteration name, description, start or end dates, or to forcibly activate it.

    • Close to end your iteration. Note that this option is available only if the iteration is active.

    • Create child to create a child iteration for the target iteration.

10. Working with codebases

After creating a space, OpenShift.io enables you to create a new application codebase or import an existing codebase from GitHub and set up pipelines to build the code.

10.1. About codebases

After creating a space, OpenShift.io enables you to create a new application codebase or import an existing codebase from GitHub and set up pipelines to build the code.

When you create a new project using the quickstart wizard, OpenShift.io creates a new code repository for your project and stores it in GitHub. OpenShift.io also maintains additional metadata for version control of your project code. OpenShift.io codebases are a generic representation of a project’s code.

Currently, codebases in OpenShift.io are GitHub code repositories. In the future, OpenShift.io may support additional git hosts and even non-git options for version control.

Prerequisites

10.2. Creating a new project

When you create a new space, the Create an Application wizard to create applications displays. If you closed the wizard earlier, click Create an Application in your space dashboard to see the wizard again. Use this wizard to create a new quickstart project as follows:

Start creating apps
Each quickstart has different requirements to run. We recommend reading the project’s README file for details about requirements.
  1. In the Name your application field, type a unique name for your new project. Ensure that the application name adheres to the listed Naming Requirements.

    Naming Requirements
  2. Select the Create a new codebase radio button and click Continue.

  3. Select the mission and runtime for your new project:

    1. In the Choose a mission section, select the the appropriate option.

    2. In the Choose a runtime section, select the appropriate runtime. When you select the options at each step, the gray arrow at the bottom of the screen turns blue.

    3. Click the blue downward arrow button to continue.

      Choose mission and runtime
  4. In the Select Pipeline section, select the appropriate option, then click the blue arrow to continue to the next step. We recommend using the first option for most use cases because it provides stages to test your changes for each pipeline build. For more information see Working with Pipelines.

    Select a pipeline
  5. In the Authorize Git Provider section, you must provide credentials for your Git provider. If you have already connected your GitHub account to OpenShift.io, you can click the blue arrow to continue.

    Authorize GitHub
  6. The next screen displays a summary of your application options. Scroll down in your browser to view the Application Information section. For this example, do not edit these options. If desired, you can change the project name, version, Group ID, which space it is in, and the target environment for your new application at this step.

    Application information
  7. Click Set Up Application to finalize your choices and create the new application.

  8. The progress screen displays a confirmation message when your application is ready.

    1. Optionally, click the blue link to view your new codebase in your Git provider.

    2. When ready, click View New Application.

      Application ready

Your new project is now created in your space and your space dashboard now displays your new codebase.

OpenShift.io has now hosted the project source code in the linked account and specified organization on GitHub. It has also hosted the pipeline for the project in OpenShift Online.

10.3. Importing your project

After creating a space, the Create an Application wizard to create applications displays. If you closed the wizard earlier, click Create an Application in your space dashboard to see the Create an Application wizard again.

  1. In the Name your application field, type a unique name for your new project. Ensure that the application name adheres to the listed Naming Requirements.

    Naming Requirements
  2. Select the Import an existing codebase radio button and then click Continue to import an existing project codebase into OpenShift.io.

    Importing Project
  3. In the Authorize Git Provider step:

    1. Click the Location drop-down to select the location of your codebase. The default option is your personal GitHub account name.

    2. In the Repository field, click Select Repository to select the repository from which you want to import the codebase.

    3. Click the blue arrow at the bottom of the screen to continue.

      Personal organization
  4. In the Select pipeline step, select an option for your pipeline build, then click the blue arrow to continue to the next step. We recommend using the first option for most use cases because it provides an end to end pipeline that moves your application through all the stages of application development, that is, build your source code, test your changes, rollout to stage, review, approve, and promote it to run in production.

    Select a pipeline
  5. The Confirm Application Summary & Import step displays a summary for your imported code. Review the information and click Import Application to confirm.

  6. The progress screen displays when your code is imported. Click View New Application to continue when all the steps have a green check mark next to them.

    Final step adding codebase

You have now imported the code from your existing repository to OpenShift.io.

11. Working with Pipelines

11.1. About pipelines

Pipelines define how your application is deployed. Each pipeline has multiple stages with a varying set of capabilities. They are crucial to ensure a continuous delivery system that test and deploy the code at each step to provide feedback to the user. Examples of such steps are unit testing, performance, integration, and deployment. Each step of the pipeline implements a different level of testing and deployment tasks, provides results, and then passes the code on to the next step.

In OpenShift.io, you configure a pipeline build when creating or importing a project. The pipeline build is triggered when a collaborator commits a change to the code repository.

11.2. Creating a new project

When you create a new space, the Create an Application wizard to create applications displays. If you closed the wizard earlier, click Create an Application in your space dashboard to see the wizard again. Use this wizard to create a new quickstart project as follows:

Start creating apps
Each quickstart has different requirements to run. We recommend reading the project’s README file for details about requirements.
  1. In the Name your application field, type a unique name for your new project. Ensure that the application name adheres to the listed Naming Requirements.

    Naming Requirements
  2. Select the Create a new codebase radio button and click Continue.

  3. Select the mission and runtime for your new project:

    1. In the Choose a mission section, select the the appropriate option.

    2. In the Choose a runtime section, select the appropriate runtime. When you select the options at each step, the gray arrow at the bottom of the screen turns blue.

    3. Click the blue downward arrow button to continue.

      Choose mission and runtime
  4. In the Select Pipeline section, select the appropriate option, then click the blue arrow to continue to the next step. We recommend using the first option for most use cases because it provides stages to test your changes for each pipeline build. For more information see Working with Pipelines.

    Select a pipeline
  5. In the Authorize Git Provider section, you must provide credentials for your Git provider. If you have already connected your GitHub account to OpenShift.io, you can click the blue arrow to continue.

    Authorize GitHub
  6. The next screen displays a summary of your application options. Scroll down in your browser to view the Application Information section. For this example, do not edit these options. If desired, you can change the project name, version, Group ID, which space it is in, and the target environment for your new application at this step.

    Application information
  7. Click Set Up Application to finalize your choices and create the new application.

  8. The progress screen displays a confirmation message when your application is ready.

    1. Optionally, click the blue link to view your new codebase in your Git provider.

    2. When ready, click View New Application.

      Application ready

Your new project is now created in your space and your space dashboard now displays your new codebase.

OpenShift.io has now hosted the project source code in the linked account and specified organization on GitHub. It has also hosted the pipeline for the project in OpenShift Online.

11.3. Selecting a pipeline type

When creating a new project using the quickstart wizard, three types of Jenkins build pipelines are available for your new project:

Select a pipeline
  1. Build Release, Integration Test, Rollout to Stage, Approve, Rollout to Run is the recommended option for most projects. It provides an end to end pipeline that moves your application through all the stages of application development, that is, build your source code, test your changes, rollout to the Stage environment, review, manually approve, and promote the changes to the Run environment.

  2. Build Release, Integration Test is the most basic option. After creating the pipeline, this option runs an integration test in the Test environment but does not stage the results.

  3. Build Release, Integration Test, Rollout to Stage stages the new version of your project in the Stage environment after running integration tests.

11.3.1. Deployment information

Click Deployments on the dashboard to view the detailed Deployments screen. This view also displays different types of information depending on the type of pipeline selected for your project.

For the Build Release, Integration Test pipeline, the Stage and Run details contain no information because this pipeline type does not use these environments.

Release deployments

For the Build Release, Integration Test, Rollout to Stage option, the Stage details are available, including resource usage and the version of the project.

Release and Stage

For the Build Release, Integration Test, Rollout to Stage, Approve, Rollout to Run pipeline type, the details for both Stage and Run are listed, along with resource and pod usage.

Build

Using the Build Release, Integration Test, Rollout to Stage, Approve, Rollout to Run pipeline option is recommended because this gives you the most information and control over your project.

11.4. Staging the application

When you create a new codebase, a new build executes. The new build pipeline pushes version 1.0.1 of your new application into Stage and then, after user approval, to Run. In a build pipeline, Stage and Run are individual OpenShift projects. Stage is a production staging area to review and test your application before you approve and promote it to the Run environment. The Run environment is similar to a production environment.

  1. Click Create and then click Pipeline to see the build pipelines for your new application. Initially, the build status is No stages have started.

    UG Build 1 No Stage

    When the pipeline build is ready, it displays your application in the stage environment and waits at the Approve stage for your input.

    Pipeline First Run

    If your pipeline build does not start for more than ten minutes, you can manually start a pipeline build using the instructions at Pipeline build failure.

  2. Click the icon (rollout icon) next to Rollout to Stage in the displayed pipeline to review your staged application. OpenShift Online provides this public URL to access the staged quickstart application in a new browser tab.

    Rollout to stage
    If the application does not load, see Application not available error for troubleshooting information.

Optionally, click Build #1 for the build pipeline in progress to view the build pipeline details in OpenShift Online.

A Running Pipeline Build in OpenShift Online

11.5. Promoting the application

If the application runs as expected in the staging environment approve and promote the application and build it on Run:

  1. Return to the OpenShift.io browser tab which displays the Pipeline view.

  2. Click Input Required at the Approve stage of the pipeline.

    Input Required
  3. Click Promote to promote the build from the Stage environment to the Run environment. The rollout process from Stage to Run requires several minutes.

    Promote build
  4. When the Pipeline view indicates that the application is available in the Run environment, click the icon (rollout icon) next to Rollout to Run to view the project in a new tab and test the application in the run environment.

    Rollout to Run

11.6. Viewing the build pipeline logs

Optionally, while you wait for the pipeline build, you can view the build details in the Jenkins log. For experienced users, these logs are useful when troubleshooting problems with builds if required.

  1. In the Pipeline page, click View Log for the build pipeline in progress.

    View log link
  2. When prompted, log into Jenkins with your OpenShift Online account. If an error appears instead of the log in page, wait several minutes for the Jenkins instance to initialize and then try again.

    Logging into Jenkins
  3. When logged in, the page displays the logs for your pipeline build.

    Pipeline Build Logs in Jenkins
    Do not click the Proceed or Abort options at the end of the logs.
  4. After examining the logs to familiarize yourself with the log output, you can close the browser tab and return to the OpenShift.io browser tab.

11.7. Configuring pipelines

Advanced users can change the settings for their project pipeline builds in OpenShift Online. For most users, we do not recommend changing the default values OpenShift.io sets up.

Prerequisites
  1. Ensure that you have created a build pipeline for your project. See Creating a new project for instructions.

Procedure
  1. At the top of the page, click Create and then click Pipelines to view the pipeline builds for your project.

  2. Click Edit Pipeline for the target pipeline build.

    Edit pipeline
  3. Enter your OpenShift Online credentials when prompted. When successful, you are redirected to your OpenShift Online account Console.

    OpenShift.io sets up the required default options for your pipeline build. We do not recommended changing these default settings.
  4. In this page, you can edit the following attributes for your build pipelines:

    1. Use the Source Configuration section to edit your project Git Repository URL.

    2. Use the Jenkinsfile Type option to select the source of your Jenkinsfile for the build.

    3. Use the Jenkinsfile Source Path option to provide a relative path to your Jenkinsfile.

  5. When ready, click Save to save your changes and return to the OpenShift.io browser tab.

If your pipeline build does not start for more than ten minutes, you can manually start a pipeline build using the instructions at Pipeline build failure.

11.8. Viewing the pipeline projects in OpenShift Online

To view the OpenShift Online projects that support your project pipeline, navigate to console.starter-us-east-2.openshift.com. This page displays the following projects (or namespaces) that are created in OpenShift Online:

  • The username project is where your pipelines run. This project name is your OpenShift Online user name.

  • The username-che project is for your Che Host and workspaces.

  • The username-jenkins project runs your Jenkins Master or your Jenkins Slaves. Click Monitoring after clicking this project to access your Jenkins console.

  • The username-stage project is for your personal use. In this project, pods display as running or previously run pipelines. For maintenance, click this project and power down individual pods as required.

  • The username-run project is identical to the username-stage project and is an environment for experimenting with your OpenShift pods.

12. Working with analytics

12.1. About Analytics

OpenShift.io analyzes the health of your entire stack and its dependencies and provides insights that enable you to make informed decisions on the choice of open source dependencies for your stack. It helps you augment your development stack with appropriate and secure dependencies and thus reduce the risk to your organization.

The self learning OpenShift.io analytics engine provides you information about:

  • Security issues in your stack

  • License conflicts

  • Dependencies in your stack that are not commonly used in similar stacks

Based on the analyses and comparison with similar stacks, it provides insights on:

  • Alternate dependencies to replace existing dependencies in case of usage and license outliers.

  • Additional dependencies that enhance your stack.

Based on these insights, you can create work items and follow through in the planner to update your stack as required.

The OpenShift.io analytics engine provides you these inputs at the following stages of your development project:

  • Developing or modifying your codebase in the Che IDE

  • Deploying your build pipelines

12.2. Using analytics in the development stage

OpenShift.io provides an integrated development environment in the form of an Eclipse Che workspace to develop your codebase.

OpenShift.io analytics engine analyzes your stack and its dependencies at the development stage within your Che workspace. It flags dependencies with security vulnerabilities and suggests secure, alternate versions to replace them while you develop your application codebase. You can use this analysis to develop a secure codebase with appropriate dependencies.

Procedure

You can access inputs from OpenShift.io analytics within the Che IDE as follows:

  1. In your Che workspace, open the manifest file of your project, for example, pom.xml for a Maven Stack, package.json for NPM, or requirements.txt for Python.

  2. Make modifications to your code. OpenShift.io analyzes the stack, flags the dependency if it has any security vulnerabilities, and suggests an alternate secure version.

  3. If you see an error icon (che cve issue) move the mouse pointer over the icon to see the Common Vulnerabilities and Exposures (CVE) for the flagged dependency and the suggested alternate version.

    Error Icon
  4. Update the dependencies to the suggested version.

12.3. Using analytics at the deployment stage

When you create a new quickstart project, a new build is executed. OpenShift.io analytics is triggered during the Build Release stage of the build pipeline. It analyzes your stack and its dependencies and provides a detailed report on the security issues and license issues affecting your dependencies along with insights on alternate and additional dependencies suitable for your stack. Use the stack report to make informed decisions about the open source dependencies in your stack.

Prerequisites

Ensure that you deploy your project and create a pipeline for your project.

Procedure
  1. Navigate to Create  Pipelines to view the pipeline builds for your project.

  2. In the Pipelines view, under the Build Release stage, click Stack Report to see the analysis report for your entire stack.

    Accessing stack report

    The report displays a summary of four key aspects relevant to your stack in the form of cards: Security Issues, Licenses, Insights, and Dependency Details.

    Full stack report
  3. Click each of the cards to see a detailed analysis report for your stack and its dependencies:

    Security Issues

    This card highlights the number of security issues in your stack, the highest Common Vulnerability Scoring System (CVSS) score, and the number of dependencies with this high score.

    Click the Security Issues card to see details on:

    • Dependencies with security issues

    • The number of Common Vulnerabilities and Exposures (CVEs) found in each of your dependencies

    • The highest Common Vulnerability Scoring System (CVSS) score in your dependency and its CVE ID.

      A CVSS score highlighted in:

      • Red indicates a severe vulnerability, with a score in the range of 7 - 10.

      • Orange indicates a moderate vulnerability, with a score in the range of 4 - 6.9.

    Licenses

    This card suggests an appropriate stack level license and flags conflicting, unknown, and restrictive licenses (licenses that are not commonly used in similar stacks or that do not work well with the stack’s representative license) affecting your stack.

    Click the Licenses card to see the following detailed information:

    • The Conflicting license(s) details tab is displayed by default. It lists dependencies that conflict with licenses of other dependency or with the stack level license. It highlights the licenses which are affected in the dependency, and suggests alternate dependencies that go well with your stack, and avoid such conflicts.

    • Click the Unknown license(s) details tab to see the list of dependencies with licenses unknown to OpenShift.io. It highlights the affected or unknown license, and suggests alternate dependencies to replace such dependencies.

    Insights

    Based on the analysis of other similar stacks, this card identifies usage outliers (dependencies not commonly used in similar stacks and that rarely go well together) in your stack and also highlights the number of companion (additional) dependencies that could augment your stack.

    Click the Insights card to see the following insights:

    Detailed insights
    • The Usage outliers details tab is displayed by default. It identifies and lists dependencies in your stack that are not commonly used in similar stacks or that do not work well with other dependencies in the stack. It suggests alternate dependencies, suitable to your stack, to replace them. The Confidence score depicts the confidence of OpenShift.io analytics on the suitability of the alternate dependency to your stack.

    • Click the Companion component details tab to see a list of additional dependencies that you can add to your stack to enhance it. Based on the confidence score, you can decide on the suitability of the dependency to your stack and add it. You can also provide your feedback on the suggested dependencies.

    Dependency Details

    This card lists the number of dependencies analyzed by OpenShift.io and those unknown to it.

    Click the Dependency Details card to see details on:

    • The Analyzed dependency details tab is displayed by default. It lists details of all the dependencies analyzed by OpenShift.io and the Components check section highlights security, usage, and license issues in them. It suggests alternate dependencies to replace dependencies with usage and license issues.

    • The Unknown dependency details tab lists dependencies unknown to OpenShift.io analytics.

  4. Expand the arrow adjacent to the dependency to see the following detailed information about the existing or the suggested companion dependency:

    • The current and latest available version of the dependency

    • GitHub statistics relevant to it that help assess its popularity

    • Licenses used by the dependency

    • Tags associated with the dependency

      Expand dependency

    In the case of usage outliers, details of the suggested replacement dependency are displayed along with those of the existing dependency. These statistics help you compare the existing dependency with the alternate dependency and make a smart choice for your stack.

  5. To act on the analytics and insights provided by the report:

    • In the Security Issues detailed view, click Report an issue to report the security vulnerability as an issue in the OpenShift.io planner. This ensures all your team members are aware about the security issue and can take the necessary follow-up action.

    • In the Insights detailed view, click Create work item to create auto-populated issues in OpenShift.io planner for adding the suggested alternate or companion dependency.

      Stack report wi

You can now act upon the relevant input provided by the stack report and enhance your development project.

13. Working with Che workspaces

13.1. About workspaces

After creating and then testing a new application or importing an existing application, you can make changes to the code using workspaces. OpenShift.io provides hosted instances of Eclipse Che within your browser to edit, test, and debug your project code.

One of the key features of Eclipse Che is Che workspaces, which provide a fully configured runtime environment for running your code. As a result, OpenShift.io provides a lightweight, next generation IDE as well as a containerized development and testing environment.

When you use the quickstart application wizard in OpenShift.io, the development and testing environment is automatically configured with the necessary runtime components and is ready to use. Thereby OpenShift.io uses Che workspaces to provide you with a personal development machine each time you start working on a new project.

13.2. Creating a Che workspace

To edit your project code, you must create a new Che workspace for your project.

  1. Click Create from the top of the OpenShift.io page. The default view for this tab is Codebases.

  1. In the WORKSPACES column, click Create workspace for your project.

    Create Workspace

    If you see a message about the workspaces loading (see screen capture), it indicates that your Che instance is idle. Allow several minutes for the loading process to finish.

    Loading Workspaces
  2. When your workspace is ready, it automatically loads in a new tab. Alternatively, click Open to view your new Che workspace in a new browser tab. This workspace loads the codebase for the listed project.

    New Workspace
    If a new tab does not appear, see Enable popups for troubleshooting information.
  3. As the workspace loads, the Workspace Status window at the bottom of the Che workspace tab displays the progress:

    Workspace loading

    When loaded and ready to use, the new Che workspace tab displays the following confirmation message:

Workspace Running success message

13.3. Running your project in the Che workspace

After your Che workspace loads, you can see your project code listed in the file explorer panel, in the upper-left side of the screen. You must now ensure the following prerequisites are met before you start using the workspace to edit the codebase:

Prerequisites
  • Add a new or existing codebase to OpenShift.io.

  • Create a Che workspace for your target codebase.

Procedure
  1. Click the run option from the Run button (tri run). Maven then downloads the required dependencies, compiles the application, and starts the verticle (Vert.x uses this name for deployed code). For Vert.x projects, this also sets up the server and hot deploy options. The hot deploy option automatically updates the application when you make a change.

    If the Run command macro is not defined, it displays the Create run command option instead of Run:

    Create run command

    See Create run command macro for instructions on setting up a run command.

  2. A run terminal appears at the bottom pane of the Che workspace. When the mvn build command finishes executing, the run view displays the Succeeded in Deploying verticle message:

    Successfully deployed verticle
  3. Click the blue preview URL at the top of the run view to see your application running in Che.

    Run project link

This is the same version of the application that the pipeline deployed to Stage and you subsequently promoted to Run. The URL for this build of the application is different from the URLs used by OpenShift Online for Stage and Run. This is your private sandbox hosted within Che. You can still share this URL with others and interactively debug the application while they run it in their browser.

13.4. Editing the quickstart code

Prerequisites
  • Add a new or existing codebase to OpenShift.io.

  • Create a Che workspace for your target codebase.

  • Click the run option from the Run button (tri run) to start running your project code. This allows the hot deploy feature to automatically save and deploy your changes.

Procedure

To edit your project’s code and preview the results:

  1. In your Che workstation file explorer view, double click folder and file names to navigate to the target file you want to edit.

    Navigate folders in Che workspace
  2. In the file, make the desired changes to the code. The Che workspace automatically saves your changes.

  3. To test your changes, click the blue preview URL at the top of the run view to see your application in a new browser tab.

    Preview Link
    If you already ran the application earlier as instructed in Running your project in the Che workspace, your changes are instantly implemented. Maven uses the Vert.X hot deploy feature to automatically update the application when you make a change. Return to the browser tab running the application and skip the rest of this step.

You have now learned how the workspace automatically saves and applies your changes.

13.5. Committing and pushing changes to GitHub

After making the required changes to your code, commit and push the modifications to your project GitHub repository.

Before committing your changes, ensure that your project pipeline build has completed (that is, the build has been promoted and is at the Rollout to Run stage).
Prerequisites
  • Add a new or existing codebase to OpenShift.io.

  • Create a Che workspace for your target codebase.

  • Make the required changes to your code and then run and test the code by clicking the run option from the Run button (tri run).

Procedure

  1. In the workspace browser tab, click Git from the menu options and select Commit from the displayed options.

    Git Commit Menu
  2. In the Commit to repository dialog box:

    1. Select all the changed and new files to commit.

    2. Add a commit message describing your changes.

    3. Select the Push committed changes to: check box.

    4. Click Commit.

      Commit changes

      When the commit succeeds, the following message displays:

      Pushed to origin

      You have now committed your code changes to GitHub.

13.6. Reviewing and publishing your changes

Now that we have committed and pushed our changes to GitHub, a pipeline build is automatically triggered in OpenShift.io.

Prerequisites
  • Add a new or existing codebase to OpenShift.io.

  • Create a Che workspace for your target codebase.

  • Make the required changes to your code and then run and test the code by clicking the run option from the Run button (tri run).

  • Commit your changes to your Git repository.

Procedure

To view the build:

  1. Return to the OpenShift.io browser tab.

  2. Click Create and then Pipelines to view the build pipelines. After several moments, the build pipeline stops at the Approve stage. Do not approve the build yet.

    Build #2 Runs
  3. In the Create tab, click Deployments to see the following information:

    Versions of the Application
    • Different versions of your application are now deployed to Stage and Run. Version 1.0.2 of the application, which includes your committed change to the code, is deployed to Stage because you have not yet promoted it to Run. The older version, 1.0.1, is deployed to Run because you approved it the last time the pipeline build executed.

    • The green check marks indicate that both builds are operational.

    • The 1 pod indicates that each of the application builds is scaled to one pod in OpenShift Online. The number of pods indicates the number of running instances of the application.

    • The version numbers link to individual running applications. You can use these separate staging areas to share different versions of your application before Promoting a change. Click the version numbers to view the details for that deployment.

      Expand the application version
  4. Click Pipelines to return to the pipelines view.

  5. At the Approve stage, click Input Required.

  6. Click Promote to promote version 1.0.2 of the application to Run.

    Your changes are now available on both Stage and Run. If you return to the Deployments tab, you can see the version for both Stage and Run are now 1.0.2.

    Updated applications

You have now used Che workspaces to edit the code for your project, committed the changes to GitHub, and published the new version of your project.

14. Troubleshooting

14.1. Login issues

When logging in to OpenShift.io, an error about an account already existing with your email address can display.

Login error

If you encounter this issue, the workaround is to log in using your username instead of your email address.

14.2. Enable popups

If a new tab does not appear, your browser is blocking the pop-up window that displays the new workspace. To resolve this, allow pop-up windows from https://openshift.io. In Chromium-based browsers, do the following:

  1. Click the blocked pop-up window icon in the URL field of your browser.

  2. Select the Always allow pop-ups from https://openshift.io option, and click Done.

    Blocked Pop Up
  3. Now, click Open again to load the workspace.

14.3. Application not available error

When you click Rollout to Stage or Rollout to Run, a new browser tab displays your application.

If the new tab displays a Application is not available error message (see screen capture), the application is not yet ready.

Application Does Not Exist Error

To fix this issue, wait several minutes and then refresh the page. The application then loads as expected.

14.4. Pipeline build failure

Occasionally, a pipeline build can fail due to a network connectivity issue with Maven. This displays a red line and cross in the Pipeline Build information as seen in the following screen capture:

Pipeline build failure

If you click View Log for the failed build, the build log includes error information such as the following:

[INFO] --- fabric8-maven-plugin:3.5.38:resource (fmp) @ test4 ---
Mar 22, 2018 2:54:10 PM org.apache.maven.wagon.providers.http.httpclient.impl.execchain.RetryExec execute
INFO: I/O exception (java.net.SocketException) caught when processing request to {s}->https://repo1.maven.org:443: Connection reset
Mar 22, 2018 2:54:10 PM org.apache.maven.wagon.providers.http.httpclient.impl.execchain.RetryExec execute
INFO: Retrying request to {s}->https://repo1.maven.org:443
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 50.518 s
[INFO] Finished at: 2018-03-22T14:54:12+00:00
[INFO] Final Memory: 22M/29M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal io.fabric8:fabric8-maven-plugin:3.5.38:resource (fmp) on project test4: Execution fmp of goal io.fabric8:fabric8-maven-plugin:3.5.38:resource failed: Plugin io.fabric8:fabric8-maven-plugin:3.5.38 or one of its dependencies could not be resolved: Could not transfer artifact io.fabric8:kubernetes-model:jar:2.0.4 from/to central (https://repo1.maven.org/maven2): GET request of: io/fabric8/kubernetes-model/2.0.4/kubernetes-model-2.0.4.jar from central failed: Connection reset -> [Help 1]

To resolve this issue, restart the pipeline build as follows:

  1. Click the additional options icon (kabob white) at the right side of the build.

  2. From the displayed options, select Start Pipeline.

    Manually start pipeline

The pipeline restarts and successfully completes.

14.5. Create run command macro

If your Che workspace does not already include a run command macro, clicking the Run icon displays a Create run command option:

Create run command

To create the run command:

  1. Click Create run command.

  2. Add the following information for the new command:

    1. In the Name field, type run to name the new command shortcut.

    2. In the command box, type the following command:

      scl enable rh-maven33 'mvn compile vertx:run -f ${current.project.path}'
    3. Toggle the Applicable option to YES to enable this macro for your project.

      Add details create run
  3. Click RUN on the right side of the screen to run your new macro.

    Run macros
  4. In the Terminal view at the bottom of the workspace, the command runs. When successfully complete, the command displays the following message:

    [INFO] INFO: Succeeded in deploying verticle
  5. Click SAVE to save your new macro.

    Save macro
  6. In any order, click the filesystem icon and the X icon for the run tab to close the macros options:

    Filesystem icon

You have now set up your run macro. If you click the run option at the top of your screen, it displays the new macro (tri run).

14.6. OpenShift.io Frozen on Chrome

When using OpenShift.io with Chrome, if the browser window freezes at any point, press Shift+Ctrl+r for a hard refresh. This reloads OpenShift.io and resolves the problem.

14.7. Clearing Failed Builds

If you view all your spaces and delete them manually, often this does not clear the build information in the OpenShift.io dashboard view. The failed builds appear as follows:

Clearing failed builds

This is a known issue because when a space is deleted, these builds must also be cleared from the dashboard.

To clear the dashboard:

  1. Click your name at the top right of the dashboard and then select the Profile option from the drop down menu.

    Profile menu
  2. In the profile page, click Edit Profile.

    Edit profile button
  3. In the edit profile page, click Reset Environment.

    Reset environment

This resets your OpenShift.io environment and clears the dashboard.

Glossary

This glossary provides concise definitions of terms and explanations of concepts used in Red Hat OpenShift.io and in related documentation.

alternate dependency

Dependencies recommended by OpenShift.io to replace restrictive licenses or usage outliers.

area

Use areas to organize work items to distinguish between different types or functionalities that are being worked on within a space.

backlog

A backlog is a list of work items that have not been triaged and assigned to a specific iteration.

bug

A defect that causes unexpected behavior in the software and that needs to be fixed.

companion dependency

Based on the analysis of your stack, OpenShift.io suggests additional dependencies that can add value to your stack.

epic

A big chunk of work with a common objective that may take many iterations to deliver. It is split into multiple features and backlog items that try to satisfy the different aspects of the epic.

experience

An experience is a way to address a scenario, fundamental, or a set of papercuts, each of which often have multiple realizing experiences. Often written as a demonstration script, it describes the ideal end-user work flow for realizing one or more of the associated value propositions.

feature

Features, often expressed as user stories, are required to actualize parent experiences or epics. They are scoped so that they are generally achievable within a sprint.

fundamental

A fundamental describes the basic essentials of a software product, such as quality and performance standards. It is a non-negotiable aspect of a product and its absence reduces the value provided to the user.

iteration

A development cycle used to organize, plan, and execute work items in a certain order. It comprises a logical mix of work items slated to be executed within the time frame of the iteration.

license conflict

Licenses that conflict at the stack or dependency level.

papercut

A papercut is a minor issue, often too small to be individually prioritized to be addressed; collectively, papercuts degrade the perception of the product. Grouped together, they receive higher priority and can be tackled together within a development cycle.

pipeline

Pipelines are a continuous delivery system that, at each step, tests and deploys the code to provide feedback to the user. Examples of such steps are unit testing, performance, integration, and deployment. Each step of the pipeline implements different levels of testing and deployment tasks, provides results, and then passes the code on to the next step.

product backlog item

A small unit of work that can be completed by a team within an iteration and that can be broken down into tasks. It is commonly described in the format of a user story, with clearly specified requirements, an owner, an estimated size, and ordered based on the order of execution.

restrictive license

Licenses that are not commonly used in similar stacks or that do not work well with the stack’s representative license.

requirement

Work item type group that focuses on execution oriented work item types such as feature, task, and bug.

scenario

A scenario identifies a real-world user problem to resolve. Addressing the scenario provides tangible user value. Prioritize scenarios that deliver maximum user value by evaluating their associated value propositions.

scenario-driven development

An agile development methodology focused on real-world problems, or scenarios, described in the language and from the viewpoint of the user. Scenarios deliver particular value propositions and are realized through experiences.

scrum

An iterative and incremental agile software development framework for managing product development.

security issue

OpenShift.io analyzes the CVEs of all your dependencies and flags the ones with security vulnerabilities.

space

A space is the equivalent of a project. Each iteration and work item must be attached to a space, and a team of people can be attached to a space in various roles. By default, a space contains at least one area and one iteration.

task

Work assigned to various team members to implement a feature. They are generally measured in units of 0.5 days, for example, four hours, eight hours, sixteen hours.

unknown license

Licenses unknown to OpenShift.io.

usage outlier

Dependencies in your stack that are not commonly used in similar open source stacks or that rarely work well together.

value proposition

A statement of the value provided to the user by addressing a scenario, fundamental, or papercut. Each of which can have multiple value propositions.

work item

Work items describe and keep track of work that needs to be completed. They can be assigned to collaborators within a space. Each work item must be attached to a space and an area (assigned by default). This can be used to model bugs, tasks, features, ideas, and more.

workspace

Workspaces are fully configured web-based development environments suitable for your code and runtime needs. They are runtime environments where you can modify, test, debug, or run your code.