Red Hat CodeReady Toolchain forOpenShift User Guide

Red Hat Developers Documentation Team

2019-02-15 17:54:11 UTC

Table of ContentsBefore you start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2

1. Introduction to Red Hat CodeReady Toolchain for OpenShift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3

1.1. CodeReady Toolchain overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3

1.1.1. Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3

1.2. Related information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4

2. Getting help and giving feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5

2.1. Asking questions about CodeReady Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  5

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

2.3. Send us feedback about the documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  6

3. Accessing Red Hat CodeReady Toolchain for OpenShift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  7

3.1. Signing up for the Red Hat Developers Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  7

3.2. Logging into CodeReady Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  7

3.3. Logging out of Red Hat CodeReady Toolchain for OpenShift . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8

4. Changing user preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9

4.1. Editing your profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9

4.2. Changing your password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10

4.3. Adding a GitHub organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  10

4.4. Opting in to beta features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  11

Getting Started with CodeReady Toolchain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  13

5. Working with spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14

5.1. About spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14

5.2. Creating a new space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14

5.3. Viewing spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15

5.4. Deleting an existing space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  15

6. Working with codebases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  16

6.1. About application codebases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  16

6.2. Creating a new application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  16

6.3. Importing your codebase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  19

7. Working with Pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20

7.1. About pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20

7.2. Selecting a pipeline type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20

7.3. Reviewing the staged application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20

7.4. Promoting the application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  21

7.5. Viewing the build pipeline logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  22

7.6. Configuring pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  23

7.7. Viewing your OpenShift Online projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  24

8. Working with Che workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  26

8.1. About workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  26

8.2. Creating a Che workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  26

8.3. Editing your Node.js codebase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  27

8.4. Committing and pushing changes to GitHub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  28

8.5. Reviewing and publishing your changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  29

9. Working with analytics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  30

9.1. About Analytics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  30

9.2. Using analytics in the development stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  30

9.3. Using analytics at the deployment stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  31

10. Working with areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  36

10.1. About areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  36

10.2. Creating a new area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  36

10.3. Associating a work item with an area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  37

11. Working with collaborators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  38

11.1. About collaborators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  38

11.2. About roles and permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  38

11.3. Adding collaborators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  38

11.4. Viewing collaborators in the space and managing their roles . . . . . . . . . . . . . . . . . . . . . . . . .  39

11.5. Assigning a work item to a collaborator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  40

12. Working with work items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  42

12.1. About work items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  42

12.2. Creating a new work item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  42

12.3. Updating a work item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  44

12.4. Viewing work items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  45

12.5. Filtering work items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  46

13. Working with iterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  48

13.1. About iterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  48

13.2. Creating a new iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  48

13.3. Associating a work item with an iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  49

13.4. Using iterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  49

14. Working with CodeReady Toolchain resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  51

14.1. Viewing resource usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  51

14.2. Reviewing detailed resource information in OpenShift Online. . . . . . . . . . . . . . . . . . . . . . . .  51

15. Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  54

15.1. Login issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  54

15.2. Enable popups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  54

15.3. Application not available error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  55

15.4. Pipeline build failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  55

15.5. Create run command macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  57

15.6. CodeReady Toolchain Frozen on Chrome . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  59

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  60

The guide describes the features of Red Hat CodeReady Toolchain for OpenShift.It also contains information about potential problems users may encounterwhile using the software. Where possible, workarounds are described foridentified issues.

Before you start

Chapter 1. Introduction to Red HatCodeReady Toolchain for OpenShiftRed Hat Developer Program offers a Software as a Service (SaaS) product for developers calledRed Hat CodeReady Toolchain for OpenShift to meet your software development requirements.

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

1.1. CodeReady Toolchain overviewRed Hat CodeReady Toolchain for OpenShift is a highly collaborative open-source, web-basedapplication life cycle management (ALM) solution. It is a next-generation product for developers tomanage the development life cycle with one efficient tool. It enables you to plan, create, and deployhybrid cloud services. It utilizes many open source projects like fabric8, Eclipse Che, and OpenShiftOnline.

1.1.1. Features

CodeReady Toolchain offers features to seamlessly manage end-to-end application development. Itprovides an integrated approach to DevOps with all the tools necessary to analyze, plan, create, anddeploy services. Members of distributed teams can use it to perform the following tasks withoutleaving 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 OpenShiftOnline.

• 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-awareenvironment 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, integratedJenkins 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 betailored to the requirements of a team - you can have simple automated build pipelines or addmanual promotions.

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

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

Analysis and recommendations:

• Use the full-stack analysis feature on the software components in your application to identifypotential security issues in your source code and get suggestions on safer alternativecomponents 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 toprovide useful real-time assistance for developers that learns and improves over time.

1.2. Related informationSee also the following related Red Hat resources related to the Red Hat Developer Program:

• Red Hat Developers

• Red Hat Developer Blog

Chapter 2. Getting help and giving feedbackCodeReady Toolchain follows a continuous delivery model. Updates and changes to the system aredelivered continuously, often multiple times in a day. Hearing directly from you about yourexperiences lets us improve the product and experience for you. Use the following options to gethelp, raise bugs, request for features, and provide feedback.

2.1. Asking questions about CodeReady ToolchainThe CodeReady Toolchain MatterMost chat channel is the best way to ask questions or getimmediate help for CodeReady Toolchain at any time. We encourage users to ask their question ordiscuss 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 theappropriate channel.

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

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

2.2. Send us feedback about Red Hat CodeReadyToolchain for OpenShiftTo give the CodeReady Toolchain team feedback, create an issue and send us a description of theproblem with the necessary details and screenshots if necessary. You can also search for relatedissues at this link.

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

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

2.3. Send us feedback about the documentationThe documentation team welcomes all feedback or requests for information that is helpful to youbut 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.

Chapter 3. Accessing Red Hat CodeReadyToolchain for OpenShiftThis section explains how to register and gain access to Red Hat CodeReady Toolchain forOpenShift. It also outlines how to log in to and log out of the service.

3.1. Signing up for the Red Hat Developers ProgramTo start using CodeReady Toolchain, create a new Red Hat Developers (RHD) account or use anexisting 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:

i. At the CodeReady Toolchain Developer page, click [ Register ].

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

iii. Select the terms and conditions check boxes.

iv. Click [ Create my account ].

v. Verify your email address to complete registration.

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

i. Click the appropriate social account button.

ii. Add your login credentials for the selected service and authorize the creation of theaccount.

Additional resources:

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

• Red Hat Developer Program Benefits

• Red Hat Enterprise Linux Developer Suite

• Red Hat Enterprise Linux Developer Workstation

• Red Hat Enterprise Linux Developer Support

3.2. Logging into CodeReady Toolchain

When you sign up to use CodeReady Toolchain, you are given an OpenShiftOnline account with enough resources to run a basic stage and run environment,pipelines, and an Eclipse Che development workspace.

Prerequisites

• Ensure that you have registered for a Red Hat Developer Program account.

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:

a. Log in using your Red Hat account:

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

ii. Click [ Log In ].

b. Log in using a social account:

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

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

iii. If asked, add information about yourself on the Additional Action Required page. If theprovided email address already has an account, an option to link your social accountwith your Red Hat Developers account is available. An email arrives in the account toconfirm 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 forOpenShiftPrerequisites

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

Chapter 4. Changing user preferencesAfter logging in to CodeReady Toolchain, you can change your user preferences in the Profilesection.

4.1. Editing your profileIn the CodeReady Toolchain Profile view, use the following steps to change your personal settings:

1. Navigate to your Profile view:

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

b. Select Profile from the displayed options.

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 yourpersonal URL and Bio.

You can opt to keep your email address private from other users in CodeReadyToolchain by selecting the Private option. The default option is Public.

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 passwordIn the CodeReady Toolchain dashboard view, use the following steps to change your password:

1. Navigate to your Profile view:

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

b. 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 HatDeveloper 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 amail.

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 organization1. In a new browser tab, navigate to https://github.com/settings/organizations.

2. To create a new organization in GitHub:

a. Click [ New organization ] to create a new organization.

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

c. Under Choose your plan, select Free.

d. Click [ Create organization ].

e. In the Invite organization members screen, add users or click [ Finish ] to skip this stepand 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 Organizationaccess. Click [ Grant ] to give the new organization access.

6. Return to the CodeReady Toolchain tab in your browser.

7. Navigate to your Settings view:

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

b. Click Settings from the displayed options.

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

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, yournew organization is listed.

4.4. Opting in to beta featuresThis 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:

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

b. 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 coveredin this guide. The Production-Only Features option is recommended for users who only want

the stable CodeReady Toolchain features.

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

Getting Started with CodeReadyToolchain

Chapter 5. Working with spaces

5.1. About spacesA space is the first thing a user creates in CodeReady Toolchain. All other elements are createdwithin a space to organize them for each project.

After you create a space, you can create applications using CodeReady Toolchain quickstartcodebases or import existing codebases. You can also use the space to plan your development workusing 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, eachspace 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 itemsare to be done.

5.2. Creating a new spaceIn CodeReady Toolchain, the first step for any new project is to create a new space with a uniquename. You can then create or import codebases within the space, add collaborators, and plan yourwork using work items and iterations.

Prerequisites

• Ensure that you have logged in to Red Hat CodeReady Toolchain for OpenShift.

Procedure

Create a new space as follows:

1. In the CodeReady Toolchain home page, click [ Create a space ] in the Recent Spaces section. Ifyour 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 ].

You have now created your first space.

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

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

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

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 ( ) to sort your spaces.

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

5.4. Deleting an existing spaceIf 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 theupper-left corner of the screen.

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

3. Click the additional options icon ( ) 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.

Chapter 6. Working with codebasesAfter creating a space, CodeReady Toolchain enables you to create a new application codebase orimport an existing codebase from GitHub and set up pipelines to build the code.

6.1. About application codebasesAfter creating a space, you can use CodeReady Toolchain to create a new application codebase orimport an existing codebase from GitHub and set up pipelines to build the code. These codebasesare a generic representation of a project’s code.

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

6.2. Creating a new applicationWhen you create a new space, the Create an Application wizard to add or import codebasesdisplays. If you closed the wizard earlier, click [ Create an Application ] in your space dashboardto see the wizard again. Use this wizard to create a new quickstart application as follows:

1. In the Create an application screen:

a. In the Name your application field, type a unique name for your new project. Ensure thatthe application name adheres to the listed Naming Requirements. For this example typenodejs-app to create a Node.js application.

b. Select the Create a new codebase radio button and click [ Continue ].

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

a. In the Select a mission section, select Health Check.

b. In the Select a runtime section, select Node.js. The gray arrow at the bottom of the screennow turns blue.

c. Click the blue down-arrow button to continue.

3. In the Select Pipeline section, select the first option, then click the blue arrow to continue to thenext step. The first option is suggested for most use cases. For more information seeworking_with_pipelines.

4. In the Authorize Git Provider section, your credentials are auto-populated if you have alreadyconnected your GitHub account to CodeReady Toolchain. If your GitHub account is notconnected with CodeReady Toolchain, click Login & Authorize Account. If your browsersession is already logged in to a GitHub account, CodeReady Toolchain uses it to connect yourGitHub account with CodeReady Toolchain. If not, you are prompted to sign in to your GitHubaccount. After your GitHub account is connected, click the blue arrow to continue.

5. The next screen displays a summary of your application options. Scroll down in your browser toview the Application Information section. If desired, you can change the Application Name,

Version, and Group ID for your new application at this step. For this example, do not edit theseoptions.

6. Click [ Set Up Application ] to create the new application. The progress screen displays aconfirmation message when your application is ready.

7. 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 detailedstack analysis report, and the codebase you added.

◦ View your continuous integration pipelines

◦ Edit your application codebase in Che web IDE.

For this example, click [ Return to your dashboard ] to see your space dashboard. Your newproject is now created in your space and your space dashboard now displays your newcodebase.

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

Each quickstart application has different requirements to run. Read the project’sREADME file for details about requirements.

6.3. Importing your codebaseAfter creating a space, use the Create an Application wizard to import an existing codebase tocreate a new application. If you closed the wizard earlier, click [ Add to space ] in the upper-rightcorner 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 anexisting project codebase into CodeReady Toolchain.

3. In the Authorize Git Provider step:

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

b. In the Repository field, click Select Repository to select the repository from which youwant to import the codebase.

c. 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 tocontinue to the next step. We recommend using the first option for most use cases because itprovides an end to end pipeline that is suitable for most projects.

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

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

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

Chapter 7. Working with Pipelines

7.1. About pipelinesPipelines define how your application is deployed. Each pipeline has multiple stages with a varyingset of capabilities. They are crucial to ensure a continuous delivery system that test and deploy thecode 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 oftesting 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. Thepipeline build is triggered when a collaborator commits a change to the code repository.

7.2. Selecting a pipeline typeWhen creating a new application using the quickstart wizard, three types of Jenkins build pipelinesare available for your application:

• Build Release, Integration Test, Rollout to Stage, Approve, Rollout to Run is therecommended option for most applications. It provides an end to end pipeline that moves yourapplication 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 thechanges to the Run environment.

• Build Release, Integration Test is the most basic option. After creating the pipeline, this optionruns 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 inthe Stage environment after running integration tests.

7.3. Reviewing the staged applicationWhen you create a new application using CodeReady Toolchain codebases or importing existingones, a new build executes. The new build pipeline pushes version 1.0.1 of your new applicationinto Stage and then, after user approval, to Run. In a build pipeline, Stage and Run are individualOpenShift projects. Stage is a production staging area to review and test your application beforeyou approve and promote it to the Run environment. The Run environment is similar to aproduction 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 displaysyour application in the stage environment and waits at the Approve stage for your input.

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

2. Click the icon ( ) next to Rollout to Stage in the displayed pipeline to review and test yourstaged application. OpenShift Online provides a public URL to access the staged quickstartapplication in a new browser tab.

If the application does not load, see Application not available error fortroubleshooting information.

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

7.4. Promoting the applicationIf the application runs as expected in the staging environment approve and promote theapplication 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.

3. Click [ Promote ] to promote the build from the Stage environment to the Run environment. Therollout process from Stage to Run requires several minutes.

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

7.5. Viewing the build pipeline logsOptionally, 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 ifrequired.

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 notdisplay, wait for a few minutes for the Jenkins instance to initialize and try again. After you arelogged in, the page displays the logs for your pipeline build.

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 pipelinesAdvanced users can change the settings for their project pipeline builds in OpenShift Online. Formost 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 applicationfor instructions.

Procedure

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

2. Click Edit Pipeline for the target pipeline build.

3. Enter your OpenShift Online credentials when prompted. When successful, you are redirectedto your OpenShift Online account Console.

CodeReady Toolchain sets up the required default options for your pipelinebuild. We do not recommended changing these default settings.

4. In this page, you can edit the following attributes for your build pipelines:

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

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

c. 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 browsertab.

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

7.7. Viewing your OpenShift Online projectsTo view all the OpenShift Online projects that support your application, navigate to My Projects inthe OpenShift Online Console.

This page displays the following projects and namespaces that are created in OpenShift Online:

• The username project is where your pipelines run. Your OpenShift Online user name is thename of your project.

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

• The username-jenkins project represents your Jenkins Master for your Jenkins Slaves. Clickthis project, and then click Monitoring in the left pane to access your Jenkins console.

• The username-run project is identical to the username-stage project and is an environmentfor experimenting with your OpenShift pods and monitoring the memory usage for your

application.

• The username-stage project is for your personal use. Use this project to see the pods that arecreated when pipelines are triggered in CodeReady Toolchain. For maintenance, select thisproject and power down individual pods as required.

Chapter 8. Working with Che workspaces

8.1. About workspacesCodeReady 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, whichprovide a fully configured runtime environment for running your code. As a result, CodeReadyToolchain provides a lightweight, next generation IDE, and a containerized development andtesting environment.

When you use the quickstart to create an application in CodeReady Toolchain, the development andtesting environment in the workspace is automatically configured with the necessary runtimecomponents. Now you can use the Che workspaces as your personal development machine tomodify your application codebase.

8.2. Creating a Che workspaceCreate a new Che workspace to edit your application codebase as follows:

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

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

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

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

If the Workspace Status shows Stopped, click [ Start ] in the Workspace isnot running pane at the top, to restart your workspace.

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

8.3. Editing your Node.js codebaseWhen your Che workspace loads, edit your project code as follows:

1. In your new workspace, click the Terminal tab and run the following commands:

cd <app-name>npm test

You can commit and push changes to your GitHub repository after the npm test succeeds.

2. In the file explorer view, navigate to nodejs-app > public > java > index.html.

3. Double-click the index.html file to view it in the editor and change the text on line 51 from_using_the_greeting_service to _creating_a_hello_world_service

4. Save your changes using Ctrl+s (or Cmd+s for macOS) and click the run option from the Run

drop-down( ). This sets up the Node.js server. Unlike in the Vert.x Quickstart project, thehot deploy option is not available for Node.js applications. As a result, changes are notautomatically deployed.

5. You can see the application run in the run tab. When the application run completes, click theblue preview URL at the top of the run tab to see your project.

The application displays the changes in a new browser tab.

8.4. Committing and pushing changes to GitHubAfter making the required changes to your code, commit and push the modifications to your projectGitHub repository.

Before committing your changes, ensure that your project pipeline build ispromoted 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 ( ).

Procedure

1. In your Che workspace, click Git from the menu bar options and select Commit from thedisplayed options.

2. In the Commit to repository dialog box:

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

b. Add a commit message describing your changes.

c. Select the Push committed changes to check box.

d. Click [ Commit ].

When the commit succeeds, the following message displays:

You have now committed your code changes to GitHub.

8.5. Reviewing and publishing your changesWhen you commit and push a change to GitHub, a pipeline build is automatically triggered inCodeReady 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 ( ).

• 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 Analyze to see your space dashboard. The Applications widget displays the details ofyour deployed applications in the Stage and Run environments.

3. In the Stage section of the Applications widget, click the options icon ( ) next to the deployedapplication to view your application in the stage environment and test it.

4. After you are satisfied with your changes, click [ Promote ] to promote the next version of theapplication to Run.

Your changes are now available on both Stage and Run.

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

Chapter 9. Working with analytics

9.1. About AnalyticsCodeReady Toolchain analyzes the health of your entire stack and its dependencies and providesinsights that enable you to make informed decisions on the choice of open source dependencies foryour stack. It helps you augment your development stack with appropriate and securedependencies 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 updateyour stack as required.

The CodeReady Toolchain analytics engine provides you these inputs at the following stages of yourdevelopment project:

• Developing or modifying your codebase in the Che IDE

• Deploying your build pipelines

9.2. Using analytics in the development stageCodeReady Toolchain provides an integrated development environment in the form of an EclipseChe workspace to develop your codebase.

CodeReady Toolchain analytics engine analyzes your stack and its dependencies at thedevelopment stage within your Che workspace. It flags dependencies with security vulnerabilitiesand suggests secure, alternate versions to replace them while you develop your applicationcodebase. You can use this analysis to develop a secure codebase with appropriate dependencies.

Prerequisite

1. Create a Che workspace to develop your stack.

2. Run your application in the Che workspace.

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 MavenStack, package.json for NPM, or requirements.txt for Python.

2. Make modifications to your code. CodeReady Toolchain analyzes the stack, flags the dependencyif it has any security vulnerabilities, and suggests an alternate secure version.

3. If you see an error icon ( ) move the mouse pointer over the icon to see the CommonVulnerabilities and Exposures (CVE) for the flagged dependency and the suggested alternateversion.

4. Update the dependencies to the suggested version.

9.3. Using analytics at the deployment stageWhen you create a new quickstart project, a new build is executed. CodeReady Toolchain analyticsis triggered during the Build Release stage of the build pipeline. It analyzes your stack and itsdependencies and provides a detailed report on the security issues and license issues affecting yourdependencies 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 analysisreport for your entire stack.

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.

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 CommonVulnerability Scoring System (CVSS) score, and the number of dependencies with this highscore.

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 yourdependencies

◦ The highest Common Vulnerability Scoring System (CVSS) score in your dependency andits 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 rangeof 4 - 6.9.

Licenses

This card suggests an appropriate stack level license and flags conflicting, unknown, andrestrictive licenses (licenses that are not commonly used in similar stacks or that do not workwell 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 thatconflict with licenses of other dependency or with the stack level license. It highlights thelicenses which are affected in the dependency, and suggests alternate dependencies thatgo 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, andsuggests 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 yourstack and also highlights the number of companion (additional) dependencies that couldaugment your stack.

Click the Insights card to see the following insights:

◦ The Usage outliers details tab is displayed by default. It identifies and lists dependenciesin your stack that are not commonly used in similar stacks or that do not work well withother dependencies in the stack. It suggests alternate dependencies, suitable to yourstack, to replace them. The Confidence score depicts the confidence of CodeReadyToolchain analytics on the suitability of the alternate dependency to your stack.

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

Dependency Details

This card lists the number of dependencies analyzed by CodeReady Toolchain and thoseunknown 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 thedependencies analyzed by CodeReady Toolchain and the Components check sectionhighlights security, usage, and license issues in them. It suggests alternate dependenciesto 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 aboutthe 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

In the case of usage outliers, details of the suggested replacement dependency are displayedalong with those of the existing dependency. These statistics help you compare the existingdependency 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 securityvulnerability as an issue in the CodeReady Toolchain planner. This ensures all your teammembers 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 inCodeReady Toolchain planner for adding the suggested alternate or companion dependency.

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

Chapter 10. Working with areas

10.1. About areasAreas can organize related work items into groups to distinguish between different types orfunctionalities that are worked on within a space.

A space can include multiple child areas. As an example, your space represents your project or rootarea, and each child area represents the sub-components of your project or space.

As a creator of a space you automatically become an admin for the space. Only a space owner canadd areas to the space. Other Admins can view the areas, but cannot add new ones.

10.2. Creating a new areaWhen you create a new space, CodeReady Toolchain automatically creates a root area with thesame name as that of the space. You can create a new child area to group together related workitems by type or functionality. Each additional area within the space is created as a child of the rootarea or another existing child area in the space.

As a creator of a space you automatically become an admin for the space. Only aspace owner can add areas to the space. Other admins can view the areas, butcannot add new ones.

Prerequisites

• Create a new space or select an existing one that you created.

Procedure

1. From your CodeReady Toolchain dashboard, click the name of a space to view its dashboard.

2. In the upper-left of the screen, click the settings tab ( ), and then click Areas to display a listof areas in your space.

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

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

5. Click [ Create ] to create the new child area.

6. To view your new area, click the expand icon to the left of your root area. Your new area islisted as a child of the root area.

10.3. Associating a work item with an areaYou can group work items by type or functionality by assigning relevant areas to the work items.

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:

Prerequisites

• Create a work item or select an existing one.

• Create appropriate child areas under the default root area of the space.

Procedure

1. In the Plan tab, click on a work item to view its details in the preview.

2. In the Area field, click the root area to see the areas you can associate the work item with. Thelist of available areas for a space is set by the creator of the space.

3. Select the required area to associate the work item with that area.

Chapter 11. Working with collaborators

11.1. About collaboratorsCollaborators are members added to a space to work together as a team on a project. They can beassigned tasks related to the project which are tracked using work items.

As the creator of a space you automatically become an admin for the space. Only the creator andadmins in the space can:

• Add collaborators to the space

• View user details

• Remove them from the space

• Assign admin roles to collaborators

11.2. About roles and permissionsAdmins and collaborators have the following roles and permissions in CodeReady Toolchain:

CodeReady Toolchaincomponents

Space Creator(Default Admin)

Admin Collaborators

Areas Can view and createnew child areas

Can only view areas,cannot create them

Cannot view Settingsscreen

Collaborators Can add and removecollaborators andassign admin role tocollaborators

Can add and removecollaborators andassign admin role tocollaborators

Cannot view Settingsscreen

11.3. Adding collaboratorsYou can add other CodeReady Toolchain users as collaborators to your space and then assign workitems to each person.

Only the creator of a space and admins in the space can add collaborators to thespace, view user details, or remove them from the space.

Prerequisites

• Log in to Red Hat CodeReady Toolchain for OpenShift with a valid user account.

• Create a new space or select an existing one you have admin rights to.

• Ensure that the user you want to add as a collaborator has a CodeReady Toolchain account.

Procedure

1. In your CodeReady Toolchain home page, click the name of the space from the list of your

Recent Spaces to view the dashboard for the space.

2. Click Add Collaborators 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 ascollaborators to the space.

4. From the displayed results, select the name of one or multiple users to add as collaborators foryour 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.

11.4. Viewing collaborators in the space and managingtheir rolesAfter adding collaborators, you can view their details, assign them as admins, or remove them fromyour space if needed.

Only the creator of a space, and admins in the space can:

• View collaborator details

• Remove them from the space

• Assign admin roles to collaborators

You can view the details of collaborators in your space, assign them as admins, or remove themfrom the space as follows:

Prerequisites

• Log in to Red Hat CodeReady Toolchain for OpenShift with a valid user account.

• Create a new space or select an existing one you have created.

• Ensure you have added collaborators to your space.

Procedure

1. Click the settings tab ( ) at the top of the screen, and then click Collaborators to see the list ofcollaborators in your space.

2. From the displayed list click the options icon ( ) next to the collaborator’s email ID.

3. You have the following options:

◦ Select View user to view the collaborator’s details such as work items and spaces associatedwith the collaborator.

◦ Select Make admin to make the collaborator an admin and give the collaborator adminrights to the space.

◦ Select Remove user to remove them from the space.

11.5. Assigning a work item to a collaboratorYou can assign a work item to any of the collaborators in your space.

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

Prerequisites

• Create a work item or select an existing one.

• Ensure that the user is added as a collaborator to your space.

Procedure

1. In the Plan tab click on a work item to view its details in the preview.

2. In the Assignees field, click Add Assignee to see the list of collaborators you can assign thework item to. The list of available collaborators for a space is set by the creator or admins for aspace.

3. Select the assignees from the list, the check mark indicates that a collaborator has beenassigned.

4. Exit the dialog box to save the selection and assign the work item to the selected collaborator.

Chapter 12. Working with work items

12.1. About work itemsWork items are measurable units of work within a space that can be tracked. They are capturedrepresentations 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 projectwork. It provides an Agile development process based planning template to create different types ofwork items to track your work.

You can use the planner to change the attributes of a work item and associate them with iterationsand areas. You can assign them to collaborators in your space, track their progress, and filter themaccording to your requirements.

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

12.2. Creating a new work itemThe CodeReady Toolchain planner provides a planning template based on the agile developmentprocess for managing iterative and incremental software development.

You can create work items using the quick-add or the in-line add options:

• Use the quick-add option to quickly add work items as follows:

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

The tree view is the default view of the planner. Clear the Show Treecheck box on the upper-right of the screen to see a flat list of work items.

2. Use the quick-add option to create a work item as follows:

a. In the Add Work Item pane, use the Theme drop-down list to select the type of workitem you want to create. You can create a Theme, Epic, Story, Task, Impediment, orDefect.

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

c. Press Enter to create the work item. Alternatively, click [ Add and open ] to create thework item and see the detailed view for the work item.

• Use the in-line add option in addition to the quick-add option to create agile-based, hierarchicalwork items with parent-child relations as follows:

1. In the Plan tab, use the quick-add option to create a high level, planning oriented Theme, asfollows:

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

b. Press Enter to create the work item. Alternatively, click [ Add and open ] to create thework item and see the detailed view for the work item.

2. Use the in-line add option to create a hierarchical child Epic for the Theme as follows:

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

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

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

3. 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 workitems.

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

12.3. Updating a work itemAfter you create a new work item click the detailed view icon ( ) next to the work item to furthermodify it’s attributes as follows:

Before closing the detailed view ensure that all your changes to the work item areindividually saved.

1. To modify the title of the work item, click the title of the work item, make your changes, andpress Enter to save the change.

2. To change the work item type, in the Type field, click the work item type and select theappropriate type to update the work item.

3. To track the state of completion of your work item, in the State field, click the new drop-downlist and select the appropriate state. By default, a freshly created work item is assigned the newstate.

4. To assign the work item to collaborators in the space, in the Assignees field, click Add Assigneeto select the collaborators from the drop-down list and exit the dialog box to save the selection.The list of available collaborators for a space is set by the creator or admins for a space.

5. To associate the work item with an appropriate area, in the Area field, click the root area toselect the required child area from the drop-down list. The list of available areas for a space isset by the creator of the space.

6. To assign the iteration in which the work item is to be completed, in the Iteration field, click theroot iteration to select the appropriate child iteration from the drop-down list.

7. To assign appropriate labels to the work item, in the Labels field, click Assign label(s) to seethe available labels in your space, select the suitable labels, and close the dialog box to save theselection. You can click Create new label to add new labels to the space and click on the color toassign a new color to the label.

8. Use the Description field to add more information about the work item. Preview the renderedmarkdown of your description in the Preview tab and click ✓ to save the description. You canuse the pencil icon to edit your saved description.

9. Expand the Links section to see Existing links or create links to other work items as follows:

a. In the Create Link section click blocks to select the appropriate relationship you want toestablish between the work items.

b. Click None and type the title or the ID to search and select the work item you want to linkthis work item to.

c. Click Create Link to save the relationship. The linked work item is now listed underExisting links.

10. Use the Comments field, to add comments to the work item. Preview the rendered markdownof your description in the Preview tab and click ✓ to submit your comment. You can use thepencil icon to edit your saved comment.

In addition to the standard markdown syntax, refer to these extensions for moreinformation about the syntax used in the Description and Comments fields.

See modifying a work item for detailed information about modifying a work item

12.4. Viewing work itemsYou can use the planner to create work items, group them into work item type groups for efficientplanning, and associate them with iterations for effective execution.

The left pane of the planner displays the iterations you create and the filters you save. Use the HidePanel or Show Panel icon to hide or display the panel as required.

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

Using the tree view

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

The tree view:

• Displays the list of work items in a hierarchical structure, along with the linked parent andchild 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 aredisplayed above the Add Work Item pane. Since the tree view displays the workitems matching your filter and their parent and child work items, the number ofwork 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 as follows:

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

2. Select the required iteration in the left pane of the planner to see the list of work itemsassociated to the iteration.

• By default, closed work items are not listed in the work item list. Select theShow Completed check box on the upper-right of the screen to see the closedwork items.

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

Reordering work items

You can reorder the work items in the list according to their priority or the order of execution bydragging the work items to the required position.

In the tree view, only work items which are on the same level in the treehierarchy can be moved.

12.5. Filtering work itemsYou 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 filterwork items by Assignee, Creator, Area, Workitem type, State, Label and Title. The drop-downnext to the Select drop-down auto-populates options based on the selected filter criteria.

3. Click the Filter by selected filter criteria drop-down to see a list of valid options for theselected 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.

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 appliedfilters are displayed at the top of the filtered work item list. For example, you can see all theopen tasks in your space by adding the state: open and the workitemtype: Task filterssuccessively.

6. If you are not satisfied with the filters, click x next to the filter criteria to clear that filter, or usethe 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 thefilter to save the filter under My Filters in the left pane. In the above example, save the multiplefilters you added as Open Tasks to track all your open tasks in the future.

8. You can modify an existing filter as follows:

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

b. Add another filter or delete an existing filter as required and save the filter with a newname. In the above example, select the Open Tasks filter and add the filter Assignee: yourusername to see open tasks assigned to you. Save this filter as My Open Tasks for future use.

9. To delete an existing filter, in the left pane, use the options ( ) icon adjoining the filter to deleteit.

Chapter 13. Working with iterations

13.1. About iterationsIterations are development cycles in the context of incremental development processes. Useiterations to prioritize work items and to implement them within a development cycle. When usedwith the Agile or the Scenario Driven Development templates, iterations can be utilized to modelsprints.

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

13.2. Creating a new iterationAdd iterations to your space to plan and organize your work items. Click Plan to view and modifyexisting iterations and to add new iterations.

Prerequisites

• Ensure that you have created a space.

Procedure

1. Click Plan to view the Planner.

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

3. Enter a Name for your new iteration.

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

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 enddate range. Alternatively, if required, toggle the Force Active switch to ON to force start theiteration. 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 currentdate falls within the start and end date range or if you force-activated it.

13.3. Associating a work item with an iterationYou 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:

Prerequisites

Create appropriate child iterations for your space.

Procedure

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

2. Select the iteration in which the work item is to be completed to associate the work item withthat iteration.

13.4. Using iterationsUse 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 todisplay the associated work items.

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

Chapter 14. Working with CodeReadyToolchain resources

14.1. Viewing resource usageA CodeReady Toolchain account with OpenShift Online provides two pods for your projects. Tocheck your resource consumption in CodeReady Toolchain, navigate to the Resources page asfollows:

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

2. In the menu options, click Resources to view the resources you have used. If you have notadded any codebases to your CodeReady Toolchain account, the page shows all resources asavailable. 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.

See Reviewing detailed resource information in OpenShift Online to view further details onresource 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 inOpenShift OnlineThe memory allowances for each OpenShift pod is 512 MiB. As a result, each application consumesnearly 1 GiB of memory for the Stage and Run environments.

After creating or adding a project to CodeReady Toolchain, you can see detailed resource usageinformation 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 resourcesused for the Run environment or username-stage to see the resources for the Stageenvironment.

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

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

4. The Pods page lists your Hello World project pod. Click the project name to see the resourceinformation for the project.

5. The Details page lists the Status of the pod and the container resource information:

Use this page to review the memory usage for your CodeReady Toolchain project. Note thisinformation and leave this tab open to compare the resource information after optimizing yourmemory usage.

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

15.1. Login issuesWhen logging in to CodeReady Toolchain, an error about an account already existing with youremail address can display.

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

15.2. Enable popupsIf a new tab does not appear, your browser is blocking the pop-up window that displays the newworkspace. To resolve this, allow pop-up windows from https://openshift.io. In Chromium-basedbrowsers, 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 ].

3. Now, click [ Open ] again to load the workspace.

15.3. Application not available errorWhen 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), theapplication is not yet ready.

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

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

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

[INFO] --- fabric8-maven-plugin:3.5.38:resource (fmp) @ test4 ---Mar 22, 2018 2:54:10 PMorg.apache.maven.wagon.providers.http.httpclient.impl.execchain.RetryExec executeINFO: I/O exception (java.net.SocketException) caught when processing request to {s}->https://repo1.maven.org:443: Connection resetMar 22, 2018 2:54:10 PMorg.apache.maven.wagon.providers.http.httpclient.impl.execchain.RetryExec executeINFO: 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 ofits dependencies could not be resolved: Could not transfer artifactio.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 -> [Help1]

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

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

2. From the displayed options, select Start Pipeline.

The pipeline restarts and successfully completes.

15.5. Create run command macroIf your Che workspace does not already include a run command macro, clicking the Run icondisplays a Create run command option:

To create the run command:

1. Click Create run command.

2. Add the following information for the new command:

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

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

scl enable rh-maven33 'mvn compile vertx:run -f ${current.project.path}'

c. Toggle the Applicable option to YES to enable this macro for your project.

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

4. In the Terminal view at the bottom of the workspace, the command runs. When successfullycomplete, the command displays the following message:

[INFO] INFO: Succeeded in deploying verticle

5. Click SAVE to save your new macro.

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

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

15.6. CodeReady Toolchain Frozen on ChromeWhen using CodeReady Toolchain with Chrome, if the browser window freezes at any point, pressShift+Ctrl+r for a hard refresh. This reloads CodeReady Toolchain and resolves the problem.

GlossaryThis glossary provides concise definitions of terms and explanations of concepts used in Red HatCodeReady Toolchain for OpenShift and in related documentation.

alternate dependency

Dependencies recommended by CodeReady Toolchain analytics to replace restrictive licenses orusage outliers.

area

Use areas to organize work items to distinguish between different types or functionalities thatare 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 thatcan 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 storiesspanning over multiple iterations to be realized. It could comprise a short statement or phrase, acoherent 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 whichoften have multiple realizing experiences. Often written as a demonstration script, it describesthe 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 andperformance standards. It is a non-negotiable aspect of a product and its absence reduces thevalue provided to the user.

impediment

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

iteration

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

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 receivehigher 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 toprovide 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 deploymenttasks, 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 brokendown into tasks. It is commonly described in the format of a user story, with clearly specifiedrequirements, 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’srepresentative 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 providestangible user value. Prioritize scenarios that deliver maximum user value by evaluating theirassociated 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 valuepropositions and are realized through experiences.

scrum

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

security issue

CodeReady Toolchain analytics examines the CVEs of all your dependencies and flags the oneswith 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 atleast one area and one iteration.

story

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

task

Work assigned to various team members to implement a feature. They are generally measuredin 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-levelfocus 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 indicategreater time criticality. It indicates the importance of meeting a deadline to derive maximumbusiness 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 thatrarely work well together.

value proposition

A statement of the value provided to the user by addressing a scenario, fundamental, orpapercut. 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 tocollaborators 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 codeand runtime needs. They are runtime environments where you can modify, test, debug, or runyour code.