Creating toolchains

Creating a toolchain from a template by using the console

You 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. Log in to IBM Cloud.

2. From the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains.

3. On the Toolchains page, click Create a Toolchain.

4. On the Create a Toolchain page, click a toolchain template.

5. 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 "Develop and test microservices with Kubernetes and Helm" toolchain template on IBM Cloud Public contains four instances of GitHub and four instances of Delivery Pipeline.

   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.

   

6. Review the default information for the toolchain settings:

   • The toolchain's name identifies it in IBM Cloud. If you want to use a different name, change the toolchain's name.
   • The region to create the toolchain in. If you want to use a different region, select it from the list of available regions.
   • The resource group to create the toolchain in. If you want to use a different resource group, select it from the list of available resource groups.
   • The provider for your source repository, such as GitHub, GitLab, or Bitbucket. If you want to use a different source provider, select it from the list of available repos.

7. 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 toolchain workflows:

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

   f. To validate that your Key Protect or Secrets Manager 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 or Secrets Manager instances.

8. 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. For example, when you create a "Develop and test microservices with Kubernetes and Helm" 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 Event Notifications, the toolchain is set up to send event notifications to the Event Notifications service that you specified.
   • 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.

   You can now distribute event notifications by using the Event Notifications tool integration. IBM Cloud Event Notifications is the preferred method for distributing notifications to PagerDuty and other communication channels such as Slack, email, SMS, push notifications, webhook, Microsoft® Teams, ServiceNow, and IBM Cloud Functions. For more information about using Event Notifications, see Enabling event notifications for toolchains.

Creating a toolchain from an app by using the console

You 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 repo, the pipeline automatically builds and deploys the app.

1. If you used IBM Cloud Public to create your app, it is configured for continuous delivery from a new GitHub 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. If you want 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. 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.

Creating a toolchain with the API

1. Obtain an IAM bearer token. Alternatively, if you are using an SDK, obtain an IAM API key and set the client options by using environment variables.

   export CD_TOOLCHAIN_AUTH_TYPE=iam && \
   export CD_TOOLCHAIN_APIKEY={iam_api_key} && \
   export CD_TOOLCHAIN_URL={base_url}
   

2. Look up the ID of the resource group in which you want to create your toolchain.

3. Choose the region in which you want to create your toolchain.

4. Create an instance of the toolchain.

   curl -X POST \
     "{base_url}/toolchains" \
     -H 'Authorization: Bearer {token}' \
     -H 'Content-Type: application/json' \
       -d '{
       "name": "{toolchain_name}",
       "resource_group_id": "{resource_group_id}"
     }'
   

   const CdToolchainV2 = require('@ibm-cloud/continuous-delivery/cd-toolchain/v2');
   const toolchainService = CdToolchainV2.newInstance();
   ...
   (async() => {
      const toolchainPrototypeModel = {
         description: {toolchain_description},
         name: {toolchain_name},
         resourceGroupId: {resource_group_id}
      };
      const response = await toolchainService.createToolchain(toolchainPrototypeModel);
   })();
   

   import (
       "github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2"
   )
   ...
   toolchainClientOptions := &cdtoolchainv2.CdToolchainV2Options{}
   toolchainClient, err := cdtoolchainv2.NewCdToolchainV2UsingExternalConfig(toolchainClientOptions)
   createToolchainOptions := toolchainClient.NewCreateToolchainOptions({toolchain_name}, {resource_group_id})
   createToolchainOptions.SetDescription({toolchain_description})
   toolchain, response, err := toolchainClient.CreateToolchain(createToolchainOptions)
   

   from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
   ...
   toolchain_service = CdToolchainV2.new_instance()
   toolchain = toolchain_service.create_toolchain(
      description = {toolchain_description},
      name = {toolchain_name},
      resource_group_id = {resource_group_id}
   )
   

   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.CdToolchain;
   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.model.*;
   ...
   CdToolchain toolchainService = CdToolchain.newInstance();
   CreateToolchainOptions createToolchainOptions = new CreateToolchainOptions.Builder()
      .description({toolchain_description})
      .name({toolchain_name})
      .resourceGroupId({resource_group_id})
      .build();
   Response<ToolchainPost> response = toolchainService.createToolchain(createToolchainOptions).execute();
   ToolchainPost toolchain = response.getResult();
   

The following table lists and describes each of the variables that are used in the previous steps.

For more information about creating toolchains with the API, see Create a toolchain in the IBM Cloud API Docs.

Creating a toolchain with Terraform

1. To install the Terraform CLI and configure the IBM Cloud provider plug-in for Terraform, follow the tutorial for Getting started with Terraform on IBM Cloud®.

2. Create a Terraform configuration file that is named main.tf. In this file, add the configuration to create a toolchain by using the HashiCorp Configuration Language. For more information about using this configuration language, see the Terraform documentation.

   The following example creates a toolchain by using the ibm_cd_toolchain resource.

   data "ibm_resource_group" "group" {
     name = "default"
   }
   
   resource "ibm_cd_toolchain" "cd_toolchain" {
     name              = "my toolchain"
     resource_group_id = data.ibm_resource_group.group.id
   }
   

   For more information about ibm_cd_toolchain, see the argument reference details in the Terraform Registry Documentation.

3. Initialize the Terraform CLI.

   terraform init
   

4. Create a Terraform execution plan. This plan summarizes all of the actions that must run to create a toolchain.

   terraform plan
   

5. Apply the Terraform execution plan. Terraform takes all of the required actions to create the toolchain.

   terraform apply