A toolchain is a set of tool integrations that support development, deployment, and operations tasks. The collective power of a toolchain is greater than the sum of its individual tool integrations.

Open toolchains are available in the Public and Dedicated environments on IBM Cloud . We can create a toolchain in two ways: use a template to create a toolchain or create a toolchain from an app.

Each toolchain is associated with a specific resource group or organization (org). If a toolchain is associated with a resource group, any user that has Identity and Access Management (IAM) Viewer permission for the toolchain resource or the resource group that contains it can access the toolchain. If the toolchain is associated with an org, any user that is a member of that org can be added to the access control list for any of its associated toolchains. For more information about access control for toolchains in Cloud Foundry orgs, see Managing user access to toolchains in Cloud Foundry orgs. For more information about access control for toolchains in resource groups, see Managing user access to toolchains in resource groups.

On IBM Cloud Public, depending on the template or toolchain that you use, the toolchain might include a GitHub or Git repository (repo) that is populated with app starter code and a preconfigured delivery pipeline. When you push changes to the toolchain's repo, the delivery pipeline automatically builds and deploys the app to IBM Cloud.

On IBM Cloud Dedicated, depending on the template or toolchain that you use, the toolchain might include a GitHub or GitHub Enterprise repo that is populated with app starter code and a preconfigured delivery pipeline. When you push changes to the toolchain's GitHub or GitHub Enterprise repo, the delivery pipeline automatically builds and deploys the apps to IBM Cloud.

To see which toolchains and tool integrations are available, see Toolchain availability, templates, and tutorials.

Creating a toolchain from a template

We can use a template as a starting point to create a toolchain that includes a specific set of tool integrations. Depending on the template that you use, you can create a toolchain that has a specific set of tool integrations or an empty toolchain that you can add tool integrations to. Learn more about how to use the templates from the IBM Cloud Garage Method .

1. If you use IBM Cloud Public, log in to IBM Cloud.
2. If you use IBM Cloud Dedicated, log in to your Dedicated environment on IBM Cloud
3. From the IBM Cloud console, click the menu icon , and select DevOps.
4. On the Toolchains page, click Create a Toolchain.
5. On the Create a Toolchain page, click a toolchain template.

6. Review the diagram of the toolchain that you are about to create. The diagram shows each tool integration in its lifecycle phase in the toolchain.

   A few of the toolchain templates have multiple instances of a tool integration. For example, the Microservices toolchain template on IBM Cloud Public contains three instances of GitHub and three instances of Delivery Pipeline, one for each of the three microservices.

   The diagram in the following image is an example. When you create a toolchain, the diagram shows each tool integration that is part of the toolchain.

7. Review the default information for the toolchain settings:

   • The toolchain's name identifies it in IBM Cloud. To use a different name, change the toolchain's name.
   • The region to create the toolchain in. To use a different region, select it from the list of available regions.
   • The resource group or organization to create the toolchain in. Click the link to switch between selecting resource groups and orgs. To use a different resource group or org, select it from the list of available resource groups or orgs.
   • The provider for your source repository, such as GitHub, GitLab, or Bitbucket. To use a different source provider, select it from the list of available repos.

   Resource groups are available in the Dallas, Washington, London, Frankfurt, and Tokyo regions. Cloud Foundry orgs are supported in the Dallas, London, and Frankfurt regions.

8. In the Tool Integrations section, select each tool integration that you want to configure for your toolchain. A few of the tool integrations do not require configuration. For more information about configuring the tool integrations, see Configuring tool integrations.

   Many of the tool integrations that comprise a toolchain require a secret to authenticate with the Continuous Delivery service.

   A secret is credentials that can be provided in the form of a password, authentication token, API key, or certificate. For example, when you add the Delivery Pipeline tool integration to your toolchain, you must provide a secret in the form of an API key.

   a. In the Tool Integrations section, click Delivery Pipeline.

   b. Click New to create an IBM Cloud API Key.

   c. Click OK to apply your new API key.

   Each user can have a maximum of 20 API keys.

   d. Click OK to create the API key without saving a secure copy of the key.

   e. To securely save the API key so that you can use it again in other toolchains and starter kit workflows:

   • Select the Save this key in a secrets store for reuse checkbox to integrate with the default IBM Key Protect secrets store.
   • If you don't have an existing instance of Key Protect, specify a name for the instance and the secret.
   • Click OK to apply your new API key.

   f. To validate that your Key Protect instance was successfully created, go to your IBM Cloud Resource list and expand the Services twistie. To view your API keys, from the menu bar, click Manage > Access (IAM), and select IBM Cloud API keys.

   g. The API key that you created and copied to Key Project is now available for use on the Create a Toolchain page. Any tool integration that requires a secret displays a key icon. Click the key icon to open a Secrets Picker dialog box to retrieve secrets from one or more Key Protect instances.

9. Click Create. Several steps run automatically to set up your toolchain. The tool integrations that are set up are different depending on which toolchain template you selected and whether you are using IBM Cloud Public or IBM Cloud Dedicated. For example, when you create a Microservices toolchain on IBM Cloud Public, these steps are run:

   • The toolchain is created.
   • If you configured Delivery Pipeline, the pipelines are created and triggered.
   • If you configured Sauce Labs, the toolchain is set up to add Sauce Labs test jobs to the pipelines.
   • If you configured PagerDuty, the toolchain is set up to send alert notifications to the PagerDuty service that you specified.
   • If you configured Slack, the toolchain is set up to send notifications about deployment status to the Slack channel that you specified.
   • If you configured a source code tool integration such as GitHub, the sample GitHub repo is cloned into your GitHub account.

Creating a toolchain from an app

We can create a toolchain from your app. The toolchain can support continuous development, deployment, monitoring, and more, and it is associated with your app. Each app can be associated with a toolchain. When you push changes to the toolchain's GitHub or GitHub Enterprise repo, the pipeline automatically builds and deploys the app.

If you created your app by using your own code repository, click Deploy my app on your app's details page. Then, follow the steps that are described in Creating apps from your own code repository.

1. If you created your app by using a starter kit, click Deploy my app on your app's details page. Next, select a deployment target. If you use IBM Cloud Public, your app is configured for continuous delivery from a new GitHub repo that is populated with the app starter code. If you use IBM Cloud Dedicated, your app is configured for continuous delivery from a new GitHub or GitHub Enterprise repo that is populated with the app starter code.
2. On the toolchain configuration page, review the diagram of the toolchain that you are about to create. The diagram shows each tool integration in its lifecycle phase in the toolchain.
3. Review the default information for the toolchain settings. The toolchain's name identifies it in IBM Cloud. To use a different name, change the toolchain's name.
4. In the Tool Integrations section, select each tool integration that you want to configure for your toolchain. A few of the tool integrations do not require configuration. For more information about configuring the tool integrations, see Configuring tool integrations.

5. Click Create. Several steps run automatically to set up your toolchain. The tool integrations that are set up are different depending on whether you are using toolchains on IBM Cloud Public or IBM Cloud Dedicated. For example, when you create a toolchain from an app on IBM Cloud Public, these steps are run:

   • The toolchain is created.
   • If you configured Delivery Pipeline, the pipelines are created and triggered.
   • If you configured GitHub, the sample GitHub repo is cloned into your GitHub account.

Viewing a toolchain

Viewing a toolchain in the console

After you configure the toolchain and its tool integrations, you can view a visual representation of the toolchain.

We can view a toolchain from an app by clicking the toolchain name from your app's details page.

1. From the IBM Cloud console, click the menu icon , and select DevOps.
2. On the Toolchains page, select a Resource Group or Location. All of the toolchains that are contained within the selected resource group or Cloud Foundry org are displayed. Click the toolchain that you want to view to open its Overview page. Alternatively, on the App details page in your app, click the toolchain name.

3. To access a tool integration that is in your toolchain, click the tool.

   If you've more than one GitHub, GitHub Enterprise, or Git repo, you might have multiple cards for the same tool integration because each repo is represented by its own card. If you've more than one pipeline, you might have multiple cards for the same tool integration because each pipeline is represented by its own card. For example, when you create a Microservices toolchain, each of the three microservices has its own GitHub, GitHub Enterprise, or Git repo and its own pipeline.

Viewing a toolchain by using the CLI

The command-line interface (CLI) toolchain view depends on the currently targeted resource group. Use the following commands to identify or change your currently targeted resource group.

• To view the currently targeted resource group, run the following command:

          
        ibmcloud target
  

• If no resource group is set, or if you would like to change the resource group, run the following command:

          
        ibmcloud target -g [resource-group]
  

• To view toolchains in the targeted resource group, run the following command:

          
        ibmcloud dev toolchains
  

• To view the details for a specific toolchain, run the following command:

          
        ibmcloud dev toolchain-get [toolchain-name]
  

• To view the toolchain details in a browser, run the following command:

          
        ibmcloud dev toolchain-open [toolchain-name]
  

Take a tutorial: Using toolchains

Check out one of these tutorials on the IBM Cloud Garage Method:

• Create and use your first toolchain by using the "Develop a Cloud Foundry app" toolchain.

• Add a toolchain to an app.

• Use the "Develop and test microservices on Cloud Foundry" toolchain.