The guide describes the features of Red Hat CodeReady Toolchain for OpenShift. 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 CodeReady Toolchain for OpenShift

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

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

1.1. CodeReady Toolchain overview

Red Hat CodeReady Toolchain for OpenShift 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

CodeReady Toolchain 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:

  • Plan your projects and track issues using your choice of Agile methodology.

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

Project development:

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

  • Code, edit, and debug using an integrated development environment based on Eclipse Che, which provides a workspace for developing and managing your application. This context-aware environment provides the appropriate context, such as the referenced branch, repository, language, and files, for the developer and the project.

  • Interact with integrated GitHub repositories.

  • Compile and review code in pull requests as required.

  • Use the quick start wizards to create basic applications with repositories on GitHub, integrated Jenkins pipeline plugins, and a related new OpenShift project.

  • Use the importing codebase wizard to migrate legacy J2EE applications to the cloud.

Deployment and testing:

  • Build, test, deploy, and monitor 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.

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

  • Use 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 help and giving feedback

CodeReady Toolchain follows a continuous delivery model. Updates and changes to the system are delivered continuously, often multiple times in a day. Hearing directly from you about your experiences lets us improve the product and experience for you. Use the following options to get help, raise bugs, request for features, and provide feedback.

2.1. Asking questions about CodeReady Toolchain

The CodeReady Toolchain MatterMost chat channel is the best way to ask questions or get immediate help for CodeReady Toolchain at any time. We encourage users to ask their question or discuss the problem they face in the channel for a fast resolution.

If you don’t already have a MatterMost account:

  1. Navigate to the CodeReady Toolchain MatterMost chat channel and click Create one now.

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

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

  4. Sign in when prompted and when asked, select the Developers team. You are redirected to the appropriate channel.

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

In the future, navigate to the CodeReady Toolchain MatterMost channel for any questions on CodeReady Toolchain.

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

2.2. Send us feedback about Red Hat CodeReady Toolchain for OpenShift

To give the CodeReady Toolchain team feedback, create an issue and send us a description of the problem with the necessary details and screenshots if necessary. You can also search for related issues at this link.

When the issue is logged, the CodeReady Toolchain team adds appropriate tags and labels to address it at the earliest.

If you prefer email, send your feedback to the CodeReady Toolchain mailing list.

2.3. Send us feedback about the documentation

The documentation team welcomes all feedback or requests for information that is helpful to you but is not 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 CodeReady Toolchain?

Create an issue to send us your feedback.

3. Accessing Red Hat CodeReady Toolchain for OpenShift

This section explains how to register and gain access to Red Hat CodeReady Toolchain for OpenShift. 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 CodeReady Toolchain, create a new Red Hat Developers (RHD) account or use an existing RHD or social media account.

  1. Navigate to Red Hat CodeReady Toolchain for OpenShift.

  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 CodeReady Toolchain 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.

Additional resources:

Use the following links to access Red Hat’s offering for developers:

3.2. Logging into CodeReady Toolchain

When you sign up to use CodeReady Toolchain, 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 CodeReady Toolchain website in a browser window.

  2. Click Log In at the top of the CodeReady Toolchain 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 CodeReady Toolchain for OpenShift

Prerequisites
  • Ensure that you have logged in to the Red Hat CodeReady Toolchain for OpenShift 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.

4. Changing user preferences

After logging in to CodeReady Toolchain, you can change your user preferences in the Profile section.

4.1. Editing your profile

In the CodeReady Toolchain 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. Select Profile from the displayed options.

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

  3. Use the displayed dialog box to edit your Name, Email, Company, and Password and add your personal URL and Bio.

    You can opt to keep your email address private from other users in CodeReady Toolchain 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 CodeReady Toolchain.

4.2. Changing your password

In the CodeReady Toolchain dashboard view, use the following steps to change your password:

  1. Navigate to your Profile view:

    1. Click your name on the upper-right corner of the screen.

    2. Click Profile from the displayed options.

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

  3. In the edit profile screen, click Change password. You are redirected to the Red Hat Developer Log In page.

  4. Click the Forgot your password button. The Reset Your Password page is displayed.

  5. Enter your username or email address to receive instructions on changing your password in a mail.

  6. In the mail you receive, click the link to reset your credentials.

  7. Fill in the required details and add your new password to the appropriate field and click SUBMIT to save the changes.

You have now successfully changed your CodeReady Toolchain password.

4.3. 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 CodeReady Toolchain 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.

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

    Refresh github
  9. After the reloaded CodeReady Toolchain 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.4. Opting in to beta features

This guide covers the Production and Beta features of CodeReady Toolchain.

In the CodeReady Toolchain home screen, 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. Select Settings from the displayed options.

  2. In the User Settings page, click the Features Opt-in option.

  3. Select the Beta Features option from the list to see the CodeReady Toolchain features covered in this guide. The Production-Only Features option is recommended for users who only want the stable CodeReady Toolchain features.

    Opt in features

    The change is applied to your profile and you receive a confirmation message.

Getting Started with CodeReady Toolchain

5. Working with spaces

5.1. About spaces

A space is the first thing a user creates in CodeReady Toolchain. All other elements are created within a space to organize them for each project.

After you create a space, you can create applications using CodeReady Toolchain quickstart codebases or import existing codebases. You can also use the space to plan your development work using work items and iterations, and assign the work items to collaborators within your team.

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 CodeReady Toolchain, the first step for any new project is to create a new space with a unique name. You can then create or import codebases within the space, add collaborators, and plan your work using work items and iterations.

Prerequisites
Procedure

Create a new space as follows:

  1. In the CodeReady Toolchain home page, click Create a space in the Recent Spaces section. If your account has an existing space, click + to create an additional space.

  2. In the Create a New Space dialog box, type a unique name for your space and click Ok.

    Create new space

You have now created your first space.

5.3. Viewing spaces

The spaces page displays all the spaces you own or collaborate in. You can sort your spaces and filter them as required. You can see the owner of each space, the number of collaborators and the number of work items associated with each space.

  1. On your Red Hat CodeReady Toolchain for OpenShift home page, click your user name in the upper-left corner of the screen.

  2. On the drop-down list, click Spaces to see a list of all the spaces you own.

    Spaces page

    Use the spaces page for the following:

    • Click Shared Spaces to see spaces you share with other collaborators.

    • Use the alphabetically ascending or descending icon (sort icon) to sort your spaces.

    • Use the Name filter to search your spaces by name.

5.4. Deleting an existing space

If a CodeReady Toolchain 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 CodeReady Toolchain for OpenShift home page, click your user name in the upper-left corner of the screen.

  2. On the drop-down list, click Spaces.

  3. Click the additional options icon (kabob white) to the right of the space you want to delete.

  4. Click Remove Space to see a dialog box asking for confirmation.

  5. Click Remove to confirm and delete your space.

6. Working with codebases

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

6.1. About application codebases

After creating a space, you can use CodeReady Toolchain to create a new application codebase or import an existing codebase from GitHub and set up pipelines to build the code. These codebases are a generic representation of a project’s code.

When you create a new application using the quickstart wizard, CodeReady Toolchain creates a new code repository for your codebase and stores it in GitHub. CodeReady Toolchain also maintains additional metadata for version control of your project code.

6.2. Creating a new application

When you create a new space, the Create an Application wizard to add or import codebases displays. If you closed the wizard earlier, click Add to space in your space dashboard to see the wizard again. Use this wizard to create a new quickstart application as follows:

Start creating apps
  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.

  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. The gray arrow at the bottom of the screen now turns blue.

    3. Click the blue down-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. The first option is suggested for most use cases. For more information see Working with Pipelines.

    Select a pipeline
  5. In the Authorize Git Provider section, your credentials are auto-populated if you have already connected your GitHub account to CodeReady Toolchain. If your GitHub account is not connected with CodeReady Toolchain, click Login & Authorize Account. If your browser session is already logged in to a GitHub account, CodeReady Toolchain uses it to connect your GitHub account with CodeReady Toolchain. If not, you are prompted to sign in to your GitHub account. After your GitHub account is connected, 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 Application Name, Version, and Group ID for your new application at this step.

    Application information
  7. Click Set Up Application to create the new application.

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

    Once your application is ready, you can do one of the following:

    • Return to the dashboard to see the details of the application deployed on stage, a detailed stack analysis report, and the codebase you added.

    • View your continuous integration pipelines

    • Edit your application codebase in Che web IDE.

      Application ready

For this example, click Return to your dashboard to see your application. Your new project is now created in your space and your space dashboard now displays your new codebase:

Space dashboard view after creating an application

CodeReady Toolchain has now hosted the project source code in the specified organization of the linked GitHub account. It has also hosted the pipeline for the project in OpenShift Online.

6.3. Importing your codebase

After creating a space, use the Create an Application wizard to import an existing codebase to create a new application. If you closed the wizard earlier, click Add to space in the upper-right corner of your space dashboard.

  1. In the Name your application field, type a unique name for your new application.

  2. Select the Import an existing codebase radio button and then click Continue to import an existing project codebase into CodeReady Toolchain.

  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.

  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 is suitable for most projects.

  5. The Confirm Application Summary & Import step displays a summary for your imported code. Review the information and click Import Application to confirm. The progress screen displays when the code is successfully imported.

  6. Click View New Application to continue when all the steps have a green check mark next to them.

You have now imported the code from your existing repository to CodeReady Toolchain.

7. Working with Pipelines

7.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 CodeReady Toolchain, you initiate a pipeline build when creating or importing a project. The pipeline build is triggered when a collaborator commits a change to the code repository.

7.2. Selecting a pipeline type

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

Select a pipeline
  • Build Release, Integration Test, Rollout to Stage, Approve, Rollout to Run is the recommended option for most applications. 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.

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

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

7.2.1. Deployment information

You can use the Deployments view to see a detailed view of your application pods in the stage and run environments, resources consumed in the two environments, and the overall resources used by the application.

At the top of the page, click Create and then click Deployments to see the deployment details.

This view also displays different types of information depending on the type of pipeline selected for your project as follows:

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

  • 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. This option is recommended because this gives you the most information and control over your project.

    Build

7.3. Reviewing the staged application

When you create a new application using CodeReady Toolchain codebases or importing existing ones, 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.

Prerequisites

Create an application or import an existing codebase to CodeReady Toolchain.

Procedure
  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. 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 and test your staged application. OpenShift Online provides a public URL to access the staged quickstart application in a new browser tab.

    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

7.4. Promoting the application

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

Prerequisites

Create an application or import an existing codebase to CodeReady Toolchain.

Procedure
  1. Return to the CodeReady Toolchain 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

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

  2. When prompted, log into Jenkins with your OpenShift Online account. If the page does not display, wait for a few minutes for the Jenkins instance to initialize and try again. Once you are 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.

You can now examine the log output to troubleshoot build problems if needed.

7.6. 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 CodeReady Toolchain sets up.

Prerequisites
  1. Ensure that you have created a build pipeline for your project. See Creating a new application 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.

    CodeReady Toolchain 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 CodeReady Toolchain 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.

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

8. Working with Che workspaces

8.1. About workspaces

CodeReady Toolchain 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, CodeReady Toolchain provides a lightweight, next generation IDE, and a containerized development and testing environment.

When you use the quickstart to create an application in CodeReady Toolchain, the development and testing environment in the workspace is automatically configured with the necessary runtime components. Now you can use the Che workspaces as your personal development machine to modify your application codebase.

8.2. Creating a Che workspace

To edit your application codebase, create a new Che workspace:

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

  2. In the WORKSPACES column, click Create workspace for your project. The workspace gets created.

  3. Click Open next to the workspace to see your Che workspace in a new browser tab.

    If a new tab does not appear, see enable_popups for troubleshooting information.

    As the workspace loads the codebase for your application, the Workspace Status window at the bottom of the Che workspace tab displays the progress:

    Workspace loading
    If the Workspace Status shows Stopped, click Start in the Workspace is not running pane at the top, to restart your workspace.

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

    Workspace Running success message

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

  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 following message:

    [INFO] INFO: Succeeded in deploying verticle
  3. Click the blue preview URL at the top of the run view to see your application running in Che.

    Run project link
  4. In the application, enter a name in the Name field and click Invoke to test the application.

    Testing the application

    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.

8.4. Editing the quickstart code

Prerequisites
  • Add a new or existing codebase to CodeReady Toolchain.

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

See Using advanced Che features to learn more about effectively using your Che workspace.

8.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 is promoted and at the Rollout to Run stage.
Prerequisites
  • Add a new or existing codebase to CodeReady Toolchain.

  • 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 your Che workspace, click Git from the menu bar options and select Commit from the displayed options.

  2. In the Commit to repository dialog box:

    1. If they are not already, select all the changed and new files to add them to the commit.

    2. Add a commit message describing your changes.

    3. Select the Push committed changes to check box.

    4. Click Commit.

When the commit succeeds, the following message displays:

Pushed to origin

You have now committed your code changes to GitHub.

8.6. Reviewing and publishing your changes

When you commit and push a change to GitHub, a pipeline build is automatically triggered in CodeReady Toolchain.

Prerequisites
  • Add a new or existing codebase to CodeReady Toolchain.

  • 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 review the build and publish your changes:

  1. Return to the CodeReady Toolchain browser tab.

  2. Click Create and then Pipelines to view the build pipelines. Wait for the build pipeline to progress to the Approve stage.

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

  4. Click Pipelines to return to the pipelines view and click Input Required at the Approve stage of the pipeline.

  5. 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 that version 1.0.2 is deployed to both Stage and Run.

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.

9. Working with analytics

9.1. About Analytics

CodeReady Toolchain 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 CodeReady Toolchain 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 CodeReady Toolchain 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

9.2. Using analytics in the development stage

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

CodeReady Toolchain 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 CodeReady Toolchain 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. CodeReady Toolchain 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.

9.3. Using analytics at the deployment stage

When you create a new quickstart project, a new build is executed. CodeReady Toolchain 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

Create an application or import an existing codebase to CodeReady Toolchain.

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 CodeReady Toolchain. 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 CodeReady Toolchain 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 CodeReady Toolchain 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 CodeReady Toolchain 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 CodeReady Toolchain 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 CodeReady Toolchain 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 CodeReady Toolchain 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.

10. Working with areas

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

10.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, CodeReady Toolchain 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 CodeReady Toolchain dashboard, click the name of a space to view its dashboard.

  2. At the top of the page, click the settings 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

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

11. Working with collaborators

11.1. About collaborators

Collaborators are members added to a space to work together as a team on a project. They can be assigned tasks related to the project which are tracked using work items.

11.2. Adding collaborators

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

Only creators of a space can add collaborators to the space, view user details, or remove them from the space.
Prerequisites
Procedure
  1. In your CodeReady Toolchain home page, click the name of a space from the list of your Recent Spaces to view the dashboard for the space.

  2. Click Add Collaborator in the upper-left corner to see the dialog box.

  3. In the Collaborators field, enter names to search for team members you want to add as collaborators to the space.

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

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

  6. Click the collaborators icon to see the collaborators you added to your space.

    Collaborators in a space

11.3. Viewing and changing collaborators

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

Only creators of a space can add collaborators to the space, view user details, or remove them from the space.
Prerequisites
Procedure
  1. Click the settings tab (equalizer) at the top of the screen, and then click Collaborators to see the list of collaborators in your space.

    List of space collaborators
  2. From the displayed list click the options icon (kabob white) next to the collaborator’s email ID.

  3. Either:

    • Select View user to view the collaborator’s details such as work items and spaces associated with the collaborator.

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

11.4. Assigning a work item to a collaborator

After adding collaborators to your space, you can assign work items to them using the Plan tab:

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.

  4. Select the assignees from the list, the check mark indicates that a collaborator has been assigned. Click X to save the selection and close the dialog window.

    Assign collaborator

The work item is now assigned to the appropriate collaborator.

12. Working with work items

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

The CodeReady Toolchain planner is a task or work item tracker to plan and execute your project work. It provides an Agile development process based planning template to create different types of work items to track your work.

You can use the planner to change the attributes of a work item, associate them with iterations, update their progress, and filter them according to your requirements.

The planner displays all work items in a flat or hierarchical list. These work items are grouped based on the agile work item types. It lists the Iterations and the work items associated to these iterations enabling effective execution of the project plan.

12.2. Creating a new work item

The CodeReady Toolchain planner provides a planning template, based on the agile development process, for managing iterative and incremental software development.

You can create work items using the quick-add or the in-line add options. The in-line add option allows you to create work items with parent-child relations easily.

Use the agile guided hierarchy to create work items of the type, Theme, Epic, Story, Task, Impediment, and Defect, as follows:

  1. Select the Plan tab at the top of the page to view the planner. The default Backlog view displays the Work Items for your space.

    The tree view is the default view of the planner, that is, the Show Tree check box is selected by default. If you cleared it, ensure that the Show Tree check box is selected to see the tree view.
  2. Use the quick-add option to create a high level, planning oriented Theme, as follows:

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

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

  3. You can use the in-line add option to create hierarchical child work items quickly. Create a child Epic for the Theme using the in-line add option as follows:

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

      Inline Add

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

      Add Epic
    2. Add a title to the Epic and press Enter to create it.

  4. Similarly, use the in-line add option to create an execution oriented child Story for the Epic, and further break down the Story into action oriented, more granular Task type of work items.

    Create Story and Tasks

    You can also create child Impediment and Defect type of work items for the Theme, Epic, or Story type of work items as required.

For more information see:

12.3. Viewing work items

You can use the planner to create work items, group 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, the iterations you create, and the filters you save. 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.

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

  • 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

Using the tree view

The tree view is the default view of the planner. Ensure that the Show Tree check box is selected to see the tree view.

The tree view:

  • Displays the list of work items in a hierarchical structure, along with the linked parent and child work items.

  • Provides you the context of the work item in relation to the broader project goals.

  • Helps you create child work items quickly based on the development template you select.

The exact count of the work items that match your filter criteria or iteration are displayed above the Add Work Item pane. Since the tree view displays the work items matching your filter and their child and parent work items the number of work items displayed may seem to vary from that displayed in the list.
Using the flat view

Use the flat list view to track work items that belong to a particular iteration or work item type group as follows:

  1. Clear the Show Tree check box to see the flat list view.

  2. Select the required iteration or work item type group in the left pane of the planner to see the list of work items that belong to the iteration or work item type group respectively.

Reordering work items

You can reorder the work items in the list according to their priority or the order of execution by dragging the work items to the required position as follows:

  1. Move the mouse pointer over the work item you want to reorder towards the vertical blue line to the left of the work item. The pointer changes to a move-cursor.

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

12.4. Filtering work items

You can filter your work item list and save them for future reference as follows:

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

  2. Click the Select drop-down list to see the filter criteria and select one of the filters. 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 criteria.

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

    For example, in the Select drop-down list, if you select State as your filter criteria, 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, Closed, Deferred, No Plan to Implement.

    Filter criteria 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 tasks in your space by adding the state: open and the workitemtype: Task filters successively.

    Multiple Filters
  6. If you are not satisfied with the filters, click x next to the filter criteria 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, for future use, click Save and add a name to the filter to save the filter under My Filters in the left pane. In the above example, save the multiple filters you added as Open Tasks to track all your open tasks in the future.

    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 Tasks filter and add the filter Assignee: your username to see open tasks assigned to you. Save this filter as My Open Tasks 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.

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

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

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

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
  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 check box to see the closed work items.

12.5.3. Assigning a work item to a collaborator

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

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

  2. Select the assignees from the list, the check mark indicates that a collaborator has been assigned. Click X to save the selection and close the dialog window.

    Assign collaborator

The work item is now assigned to the appropriate collaborator.

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

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

12.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 Assign label(s) to see the dialog box with the available labels in your space.

  2. Select the suitable labels and close the dialog box to assign the labels to the work item.

    Assign Labels

Create and assign new labels as follows:

  1. In the Labels field, click Assign label(s) to see the available labels in your space.

  2. Click Create new label to add new labels to the space.

    Add Labels
  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.

  5. To assign the label to the work item select the label and close the dialog box.

  • After the labels are created they are available for all the work items in the space.

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

12.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 in the Links section as follows:

  1. Expand the Links option to see the work items linked to this work item in the Exisitng links section.

  2. Use the Create Link section to establish relationship with another work item as follows:

    1. Click blocks to see the Choose a link type drop-down list and select the appropriate relationship you want to establish between two work items.

      You have the following options: blocks, impedes, is blocked by, is child of, is impeded by, is parent of, is related to, relates to.

    2. Click None to see the Search for work item drop-down list, type the title or the ID of the required work item and select the work item.

      Linking Work Items
    3. Click Create Link to save the relationship.

      The linked work item is now listed under Existing links.

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

13. Working with iterations

13.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 the Agile or the Scenario Driven Development templates, 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.

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

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

13.4. Using iterations

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.

    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.

14. Working with CodeReady Toolchain resources

14.1. Viewing resource usage

A CodeReady Toolchain account with OpenShift Online provides two pods for your projects. To check your resource consumption in CodeReady Toolchain, navigate to the Resources page as follows:

  1. Click your username in the upper right corner of the CodeReady Toolchain page and select Settings.

  2. In the menu options, click Resources to view the resources you have used. If you have not added any codebases to your CodeReady Toolchain account, the page shows all resources as available. If you add or import a codebase, and have not yet pushed it to the Run environment, the page shows that part of the resources for Stage are in use.

    Resources half

See Reviewing detailed resource information in OpenShift Online to view further details on resource usage in OpenShift Online.

After you create two projects, the two pods allocated to your OpenShift Online account are used up.

Future builds may fail if the required resources are not available.

14.2. Reviewing detailed resource information in OpenShift Online

The memory allowances for each OpenShift pod is 512 MiB. As a result, each application consumes nearly 1 GiB of memory for the Stage and Run environments.

After creating or adding a project to CodeReady Toolchain, you can see detailed resource usage information 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.

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

    See Viewing projects in OpenShift Online for details about the listed projects.

  3. Click Applications and then select Pods in the displayed submenu.

    Application Pods
  4. 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
  5. 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 CodeReady Toolchain project. Note this information and leave this tab open to compare the resource information after optimizing your memory usage.

15. Troubleshooting

The following section lists the common issues you may face when using CodeReady Toolchain and the workarounds to resolve them. For further information also see the Frequently asked questions.

15.1. Login issues

When logging in to CodeReady Toolchain, 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.

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

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

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

15.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).

15.6. CodeReady Toolchain Frozen on Chrome

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

Glossary

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

alternate dependency

Dependencies recommended by CodeReady Toolchain analytics 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.

business value

The value or benefit estimated to be derived by the organization or business on completion.

companion dependency

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

component

A distinct subsystem within a system that performs specific functions.

defect

A bug that causes unexpected behavior in the software.

effort

Estimate of the amount of work required to complete a work item.

epic

A large user story, with a focused goal, that may need to be split into multiple user stories spanning over multiple iterations to be realized. It could comprise a short statement or phrase, a coherent aggregation of user stories and requirements, or an idea.

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.

impediment

Any issue or blocker that slows down the velocity of a team and affects team performance or progress.

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 that is 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

CodeReady Toolchain analytics examines 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.

story

Incremental work or requirements identified to deliver a product feature. Typically, it is expressed from the user’s perspective in the following format: As a user, I want to achieve an objective, so that this purpose is met.

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.

theme

A group of user stories with a common underlying thread. They have a broad organization-level focus and are used to track related user stories.

time criticality

It captures how the business value of a work item decreases over time. Higher values indicate greater time criticality. It indicates the importance of meeting a deadline to derive maximum business value.

unknown license

Licenses unknown to CodeReady Toolchain analytics.

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.