upgrade_projects.md

copyright	lastupdated
years 2015, 2017	2017-6-23

{:shortdesc: .shortdesc} {:new_window: target="_blank"}

Upgrade your {{site.data.keyword.jazzhub_short}} project to a toolchain

{: #upgrade_projects}

{{site.data.keyword.jazzhub}} is evolving into {{site.data.keyword.contdelivery_full}}. As part of that change, projects will be upgraded to toolchains.

You can upgrade your project or wait for it to be automatically upgraded. For the best experience, make sure that you meet the prerequisites and upgrade your project as soon as possible so that you can control what your toolchain's name is and which organization it is created in. {: shortdesc}

Frequently asked questions

• My JazzHub project is associated with the UK region, but my toolchain will be in the US South region. How will this work?
• What will happen to my work items and dashboards in Track & Plan when I upgrade?
• What will happen to my code repo when I upgrade?
• What will happen to my build definitions in my project when I upgrade to a toolchain?
• I need to create an organization for my project that will be upgraded to a toolchain. I understand that I need to add a credit card to my account before I can create an organization. Will my credit card be charged?

Toolchains

{: #compare_toolchains}

Toolchains are like projects, with a few important differences:

• Projects can have only one repository (repo) and pipeline. Toolchains can have as many repos and pipelines as you need.
• Toolchains can include tools that aren't available in projects, such as Slack, Sauce Labs, PagerDuty, and {{site.data.keyword.DRA_full}}.
• Access to toolchains is managed through standard {{site.data.keyword.Bluemix_notm}} organizations. Membership is maintained at the organization level, unlike projects, where membership was maintained at the project level.

You can learn about toolchains on YouTube {: new_window} or from Getting started with {{site.data.keyword.contdelivery_short}}. {: new_window}

Prerequisites

{: #upgrade_prereqs}

• To access your upgraded project's toolchain, you need a {{site.data.keyword.Bluemix_notm}} ID. Before you upgrade, you must verify that you have an active {{site.data.keyword.Bluemix_notm}} ID. If you don't have one, sign up.
• Make sure that your {{site.data.keyword.jazzhub_short}} project owner is correct. The toolchain that is created from your project will be part of that owner's {{site.data.keyword.Bluemix_notm}} organization.
• If you're planning to start the upgrade, make sure that you're a member of every org and space that the pipeline deploys to. Any project admin can start the upgrade. However, if the admin who starts the upgrade is not a member of every org and space that the pipeline deploys to, the pipeline cannot be created. The person who starts the upgrade becomes the owner of the repo in the toolchain.
• The Eclipse Orion {{site.data.keyword.webide}} in the toolchain is separate from the {{site.data.keyword.webide}} that is associated with your project. If you use the {{site.data.keyword.webide}} and you have uncommitted changes, commit them before you upgrade.

Upgrading from a project to a toolchain

{: #project_to_toolchain}

Important: Projects at hub.jazz.net and toolchains are both hosted in the US South region. If your project was configured to deploy apps to a different region, it will still deploy apps to that region after it is upgraded to a toolchain.

When your project is ready to be upgraded, a message is displayed on the project's card and Overview page.

Tip: You can find projects that are ready to upgrade from the menu on the My Projects page:

When you start the upgrade, the pipeline stages in your project are locked. You won't be able to run or modify them. If you revert the upgrade by deleting the toolchain, the pipeline is unlocked.

If your project uses a Git repo that is hosted on JazzHub, after you start the upgrade, the repo is locked to ensure the integrity of the data that is moved to the toolchain. If you revert the upgrade by deleting the toolchain, the repo on JazzHub is unlocked.

For full details about how each type of repo is treated in the upgrade process, see the following table.

Project repo	Project type	Toolchain repo
github.com	Private or public	The same github.com repo with {{site.data.keyword.Bluemix_notm}} Public.
hub.jazz.net/git	Private or public	A new repo in {{site.data.keyword.gitrepos}} with {{site.data.keyword.Bluemix_notm}} Public.
{: caption="Table 1. Project repos mapped to toolchain repos" caption-side="top"}

Starting the upgrade process

{: #start_upgrade}

Before you start the upgrade process, you can watch it in action on YouTube {: new_window}. {: new_window}

To upgrade your project to a toolchain, follow these steps:

1. To start the upgrade process, on the banner message, click upgrade now. The "Project upgrade toolchain" page opens.

   

   For an overview of the upgrade process, read the description on that page. The toolchain will include a new pipeline that contains the same stages and jobs as the project's pipeline. In addition, the toolchain will contain a pointer to the Eclipse Orion {{site.data.keyword.webide}} that runs in {{site.data.keyword.contdelivery_short}}.

   In this example, because the project uses a public repo on github.com, the toolchain will be connected to the same GitHub repo. If your project uses a Git repo that is hosted on JazzHub, the contents of that repo will be cloned to a new repo in {{site.data.keyword.gitrepos}}, which is part of {{site.data.keyword.contdelivery_short}}.

2. To customize the toolchain, you can configure a few settings:

   • To change the name of the toolchain, edit the Name field.

     

   • To change which {{site.data.keyword.Bluemix_notm}} organization to create the toolchain in, select the organization from your account menu:

     

   Because toolchains are managed at the organization level, be sure to select an organization where the project members that need to access the toolchain already exist, or can be added.

3. If you used Track & Plan in your project, you can transfer your Track & Plan data to GitHub Issues.

   

   • Indicate whether you want to migrate your Track & Plan data.
   • By default, all of your Track & Plan data is migrated. If you prefer to migrate only the work items that are part of a specific query, specify that query.
   • Select any work item attributes that you want to map to labels in GitHub Issues.

4. Click Create. The new toolchain is created, and its Overview page is displayed.

   

   • To access your GitHub repo or the associated issue tracker, click GitHub or Issues.
   • To access your pipeline, click Delivery Pipeline.
   • To access the {{site.data.keyword.webide}}, which contains the contents of your repo that were checked out into the workspace, click Eclipse Orion {{site.data.keyword.webide}}.

   If you return to your project during the upgrade, the banner message might state that the upgrade is in progress, especially if the upgrade process involves importing source code to a new repo or importing Track & Plan work items as issues.

   

Revisiting your project

{: #revisit_projects}

You are ready to use your new toolchain. Your project is now labeled as "Upgraded," and on the Overview page, a confirmation message is displayed.

You can see which projects are upgraded by selecting Upgraded Projects from the menu on the My Projects page:

If you need to revert the upgrade, delete your toolchain. You can delete your toolchain from the More Actions menu on the toolchain's Overview page:

When you return to your project, the upgrade message is displayed again, and you can upgrade again when you are ready.

Next steps

{: #upgrade_next_steps}

1. Confirm that the upgrade is complete by refreshing your browser and checking for the message that your project was "upgraded to this toolchain" on the project Overview page:

   

   Note: If the message says "upgrade now," your upgrade failed. Click the upgrade now link to try again.

   

2. Give your team members access to the toolchain.

   • Each team member must have a valid {{site.data.keyword.Bluemix_notm}} account. Team members who don't have accounts must sign up {:new_window}.
   • Grant organization (org) members access to the toolchain from the toolchain Manage page. Existing project members are added as members of the toolchain as part of the upgrade process. For more information about access control for toolchains, see Managing access {:new_window}.
   • If a user is not a member of the org that the toolchain belongs to, add them to the org from the Manage Organizations page.
   • If your toolchain uses {{site.data.keyword.gitrepos}}, all JazzHub project members that have a valid Bluemix ID are added to the {{site.data.keyword.gitrepos}} repo with the same privileges as they had in the JazzHub project. If your JazzHub project includes members that do not have a valid Bluemix ID, they should register for one and be added to the repo. For more information about managing organizations, see Managing organizations and spaces {:new_window}.

3. Use the tools from your toolchain instead of the tools from your {{site.data.keyword.jazzhub_short}} project. For example, to edit code from a browser, use the Web IDE from your toolchain.

4. If you are using {{site.data.keyword.gitrepos}}, authenticate by using a personal access token or an SSH key. For more information about SSH keys, see Creating a personal access token or SSH key for authentication. To authenticate from an external Git client through https, follow these steps:

   1. Go to the Access Tokens page {:new_window} of your {{site.data.keyword.gitrepos}} user settings.

   2. Create a personal access token that uses api as the scope.

   3. Go to the Account page {:new_window} and find your username for {{site.data.keyword.gitrepos}}. Your username is listed in the "Change username" section and it is shown as the first part of the URL for any personal repo that you create.

   4. To authenticate with {{site.data.keyword.gitrepos}} from an external Git client through https, use your username and your personal access token.

   5. If you want to reuse the local repo of your JazzHub Git repo, point the repo to the new repo in {{site.data.keyword.gitrepos}}. From a shell in a terminal, change to the directory where the JazzHub Git repo is cloned. Enter the git remote set-url command: git remote set-url origin https://git.ng.bluemix.net/<userid>/<name-of-new-repo>

      Tip: To check which remote URLs are set to which remote names, use the git remote -v command. The default remote name is origin. If you have a more advanced setup, the form of the command is as follows: git remote set-url <remote-name-that-uses-jazzhub-repo> https://git.ng.bluemix.net/<userid>/<name-of-new-repo>

5. When your toolchain is set up and you have started to use it, consider taking all or any of these steps to ensure that no one uses your project:

   • Add a suffix to your project name to indicate that it must not be used. You might add _DO_NOT_USE to the end of the project name.
   • Update the project's description to mention that it is no longer used, and add a pointer to the toolchain.
   • Remove the members from the project.
   • When you no longer need the project, delete it.

6. Optional: To explore your project's development maturity, your team's practices, and the quality of your code base, add IBM Cloud {{site.data.keyword.DRA_short}} to your toolchain. {{site.data.keyword.DRA_short}} applies developer, team, and deployment analytics to DevOps projects. For more information, see Getting started with {{site.data.keyword.DRA_short}}.

Troubleshooting

{: #upgrade_troubleshoot}

If you encounter a problem during the upgrade process, try one or more of these troubleshooting steps:

• Check the prerequisites to make sure that you meet them. In particular, make sure that you're a member of every org and space that the pipeline deploys to.
• If the problem occurred during your first attempt to upgrade and you meet all the prerequisites, try the upgrade again.
• If your project uses Jazz SCM or IBM Hosted Git for source control, check the size of the repo. If it is larger than 500 MB, contact the DevOps services team {:new_window}.
• If you continue to encounter problems, post a question in the support forum {:new_window}. In your forum post, include the URLs to your {{site.data.keyword.jazzhub_short}} project and your {{site.data.keyword.contdelivery_short}} toolchain, and tag your post with the devops-services tag.

Frequently asked questions

{: #upgrade_faq}

My JazzHub project is associated with the UK region, but my toolchain will be in the US South region. How will this work?

{: #faq_region}

Projects at hub.jazz.net and toolchains are both hosted in the US South region. If your project was configured to deploy apps to a different region, such as the UK region, it will still deploy apps to that region after it is upgraded to a toolchain. Therefore, nothing is really changing with respect to where the data is hosted. Toolchains will be available in more regions in the future.

What will happen to my work items and dashboards in Track & Plan when I upgrade?

{: #faq_tp}

The {{site.data.keyword.contdelivery_short}} service provides issue-tracking capabilities through {{site.data.keyword.gitrepos}}, which is hosted by IBM and based on GitLab Community Edition. {{site.data.keyword.contdelivery_short}} also supports integrations with other planning and issue-tracking tools, such as GitHub Issues and JIRA.

During the upgrade process, you can choose to migrate your Track & Plan work items to Git Issues. Both GitHub Issues and {{site.data.keyword.gitrepos}} provide kanban boards and issue tracking for planning. To learn more about Issue Boards, which is the kanban feature in Git Repos and Issue Tracking, see Issue board {: new_window}.

For customers who require the same function as the deprecated JazzHub Track & Plan, a new IBM Track and Plan service on Cloud is available for purchase separately in selected countries on a per user per month basis. With this cloud service, you get full function, equivalent to Rational Team Concert™ contributor licenses, in a single tenant cloud subscription.

This new IBM Track and Plan on Cloud service provides much richer capability than the deprecated JazzHub Track & Plan, supporting process customization, project hierarchies, SAFe® and many other agile and hybrid methods, and scalability to grow beyond a single project. It is based on the latest version of Rational Team Concert 6.0.3 and will be at version 6.0.4 in the next 60 days, while JazzHub Track & Plan was based on Rational Team Concert 5.x. A data migration is possible to IBM Track and Plan on Cloud through additional services. You can contact Tom Hollowell {:new_window}, Connected Products SaaS Sales Leader, for more information.

For information on IBM Track and Plan on Cloud, or to buy online, visit IBM Marketplace {: new_window}.

To additionally purchase Build Automation and Source Code Management, Rational Team Concert on Cloud {: new_window} is an option.

What will happen to my code repo when I upgrade?

{: #faq_repo}

After you upgrade, your new Git service will be comparable to what you had before. If you used github.com with your JazzHub project, your toolchain will be connected to the same GitHub repo. If your JazzHub project used IBM Hosted Git, the contents of that repo will be cloned to a new repo in {{site.data.keyword.gitrepos}}, which is part of {{site.data.keyword.contdelivery_short}} and hosted by IBM.

For full details about how each type of repo is treated in the upgrade process, see the following table.

Project repo	Project type	Toolchain repo
github.com	Private or public	The same github.com repo with {{site.data.keyword.Bluemix_notm}} Public.
hub.jazz.net/git	Private or public	A new private or public repo in {{site.data.keyword.gitrepos}} with {{site.data.keyword.Bluemix_notm}} Public.
{: caption="Table 1. Project repos mapped to toolchain repos" caption-side="top"}

What will happen to my build definitions in my project when I upgrade to a toolchain?

{: #faq_build}

If you're building your source code by using Jazz instead of Delivery Pipeline, you must manually migrate your build definitions to Delivery Pipeline in your toolchain.

If you're using Jazz SCM as a source repo and using Delivery Pipeline to build your code, the source in Jazz SCM will be automatically moved to a Git repo. Your Delivery Pipeline configuration will remain the same except it will consume the source from the Git repo instead of the source from Jazz SCM.

I need to create an organization for my project that will be upgraded to a toolchain. I understand that I need to add a credit card to my account before I can create an organization. Will my credit card be charged?

{: #faq_charges}

As a Pay As You Go customer {: new_window}, if you use any runtime, service, or component beyond the free allotments that are listed for it in the Bluemix catalog, you will be charged. For a usage estimate, see the pricing sheet {: new_window}. For current pricing for Continuous Delivery, see the Bluemix catalog {: new_window}.

If you're an IBM employee, internal IBM projects can be billed to departments in lieu of a personal credit card. If you need to use resources beyond the free allotments for IBM employees, create a support ticket.