Working with tool integrations

Adding a tool integration by using the console

You can add tool integrations to your toolchain by using the console.

1. From the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains.
2. On the Toolchains page, click a toolchain to open its Overview page. Alternatively, on the App details page in your app, click the toolchain name.
3. To see a list of tool integrations to add, click Add tool.
4. Click a tool integration that you want to add.
5. Enter any required information to configure the tool integration.
6. Click Create Integration to add the tool integration to your toolchain.

Adding a tool integration with the API

You can add tool integrations to your 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 toolchain in which you want to create your tool integration.

3. Look up the tool_type_id value that corresponds to the tool integration that you want to add.

4. Add the tool integration within the targeted toolchain.

   curl -X POST --location --header "Authorization: Bearer {iam_token}" \
     --header "Accept: application/json" \
     --header "Content-Type: application/json" \
     --data '{ "name": "{tool_name}", "tool_type_id": "{tool_type_id}", "parameters": {tool_parameters} }' \
     "{base_url}/toolchains/{toolchain_id}/tools"
   

   const CdToolchainV2 = require('@ibm-cloud/continuous-delivery/cd-toolchain/v2');
   const toolchainService = CdToolchainV2.newInstance();
   ...
   (async() => {
      const toolPrototypeModel = {
         toolchainId: {toolchain_id},
         toolTypeId: {tool_type_id},
         name: {tool_name},
         parameters: {tool_parameters}
      };
      const response = await toolchainService.createTool(toolPrototypeModel);
   })();
   
   

   import (
       "github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2"
   )
   ...
   toolchainClientOptions := &cdtoolchainv2.CdToolchainV2Options{}
   toolchainClient, err := cdtoolchainv2.NewCdToolchainV2UsingExternalConfig(toolchainClientOptions)
   createToolOptions := toolchainClient.NewCreateToolOptions({toolchain_id}, {tool_type_id})
   createToolOptions.SetName({tool_name})
   createToolOptions.SetParameters({tool_parameters})
   tool, response, err := toolchainClient.CreateTool(createToolOptions)
   

   from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
   ...
   toolchain_service = CdToolchainV2.new_instance()
   tool = toolchain_service.create_tool(
      name = {tool_name},
      toolchain_id = {toolchain_id},
      tool_type_id = {tool_type_id},
      parameters = {tool_parameters}
   )
   

   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.CdToolchain;
   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.model.*;
   ...
   CdToolchain toolchainService = CdToolchain.newInstance();
   CreateToolOptions createToolOptions = new CreateToolOptions.Builder()
      .name({tool_name})
      .parameters({tool_parameters})
      .toolchainId({toolchain_id})
      .toolTypeId({tool_type_id})
      .build();
   Response<ToolchainToolPost> response = toolchainService.createTool(createToolOptions).execute();
   ToolchainToolPost tool = response.getResult();
   

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

Adding a tool integration with Terraform

You can add tool integrations to your 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 resource instances by using the HashiCorp Configuration Language (HCL). For more information about using this configuration language, see the Terraform documentation.

   The following example creates a Delivery Pipeline tool integration by using the ibm_cd_toolchain_tool_pipeline resource, where toolchain_id is a GUID that represents the toolchain in which to create the tool integration.

   data "ibm_cd_toolchain" "cd_toolchain" {
     toolchain_id = {toolchain_id}
   }
   
   resource "ibm_cd_toolchain_tool_pipeline" "cd_pipeline" {
     toolchain_id = data.ibm_cd_toolchain.cd_toolchain.id
     parameters {
       name = "myPipeline"
     }
   }
   

   For more information about tool integration resources, see the full list of supported tool integration resources in the IBM Cloud Terraform Registry.

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 the tool integration.

   terraform plan
   

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

   terraform apply
   

Updating a tool integration by using the console

If you deferred the configuration of a tool integration when you created a toolchain, a Configure button is shown on its card. If you configured a tool integration when you created a toolchain, you can update the configuration settings by using the console.

1. From the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains.
2. On the Toolchains page, click the toolchain that contains the tool integration that you want to update to open its Overview page. Alternatively, on the App details page in your app, click the toolchain name.
3. If you need to configure a tool integration for the first time, on its card, click Configure.
4. When you are finished configuring the tool integration, click Save Integration.
5. If you need to update a tool integration's configuration, click the Actions icon > Configure.
6. When you are finished updating the settings, click Save Integration.

Updating a tool integration with the API

If you configured a tool integration when you created a toolchain, you can update the configuration settings 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 toolchain where the tool integration exists.

3. Using the ID of the toolchain, look up the ID of the tool integration.

4. Update the tool integration within the targeted toolchain.

   curl -X PATCH --location --header "Authorization: Bearer {iam_token}" \
     --header "Accept: application/json" \
     --header "Content-Type: application/merge-patch+json" \
     --data '{ "name": "{new_tool_name}", "parameters": {new_tool_parameters} }' \
     "{base_url}/toolchains/{toolchain_id}/tools/{tool_id}"
   

   const CdToolchainV2 = require('@ibm-cloud/continuous-delivery/cd-toolchain/v2');
   const toolchainService = CdToolchainV2.newInstance();
   ...
   (async() => {
      const toolPatchModel = {
         toolchainId: {toolchain_id},
         toolId: {tool_id},
         name: {new_tool_name},
         parameters: {new_tool_parameters}
      };
      const response = await toolchainService.updateTool(toolPatchModel);
   })();
   

   import (
       "github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2"
   )
   ...
   toolchainClientOptions := &cdtoolchainv2.CdToolchainV2Options{}
   toolchainClient, err := cdtoolchainv2.NewCdToolchainV2UsingExternalConfig(toolchainClientOptions)
   toolPatchModel := map[string]interface{}{
      "name": {new_tool_name},
      "parameters": {new_tool_parameters},
   }
   updateToolOptions := toolchainClient.NewUpdateToolOptions({toolchain_id}, {tool_id}, toolPatchModel)
   tool, response, err := toolchainClient.UpdateTool(updateToolOptions)
   

   from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
   ...
   toolchain_service = CdToolchainV2.new_instance()
   tool = toolchain_service.update_tool(
      toolchain_id = {toolchain_id},
      tool_id = {tool_id},
      toolchain_tool_prototype_patch = {
         "name": {new_tool_name},
         "parameters": {new_tool_parameters}
      }
   ) 
   

   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.CdToolchain;
   import com.ibm.cloud.continuous_delivery.cd_toolchain.v2.model.*;
   ...
   CdToolchain toolchainService = CdToolchain.newInstance();
   HashMap<String,Object> toolchainToolPrototypePatch = new HashMap<>();
   toolchainToolPrototypePatch.put("name", {new_tool_name});
   toolchainToolPrototypePatch.put("parameters", {new_tool_parameters});
   UpdateToolOptions updateToolOptions = new UpdateToolOptions.Builder()
      .toolchainId({toolchain_id})
      .toolId({tool_id})
      .toolchainToolPrototypePatch(toolchainToolPrototypePatch)
      .build();
   Response<ToolchainToolPatch> response = toolchainService.updateTool(updateToolOptions).execute();
   ToolchainToolPatch tool = response.getResult();
   

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

Updating a tool integration with Terraform

If you configured a tool integration when you created a toolchain, you can update the configuration settings with Terraform.

1. Install the Terraform CLI and configure the IBM Cloud provider plug-in for Terraform by following the tutorial for Getting started with Terraform on IBM Cloud.

2. Use the Terraform configuration file that you used to create the tool integration. If your tool integration was not created with Terraform, run terraform import to avoid creating another tool integration. For more information about using this configuration language, see the Terraform documentation.

   The following example updates the name of an existing Delivery Pipeline tool integration by using the ibm_cd_toolchain_tool_pipeline resource, where toolchain_id is a GUID that represents the toolchain where the tool integration exists.

   data "ibm_cd_toolchain" "cd_toolchain" {
     toolchain_id = {toolchain_id}
   }
   
   resource "ibm_cd_toolchain_tool_pipeline" "cd_pipeline" {
     toolchain_id = data.ibm_cd_toolchain.cd_toolchain.id
     parameters {
       name = "myUpdatedPipelineName"
     }
   }
   

   For more information about tool integration resources, see the full list of supported tool integration resources in the IBM Cloud Terraform Registry.

3. Initialize the Terraform CLI.

   terraform init
   

4. Create a Terraform execution plan. This plan summarizes all of the actions that must run to modify the tool integration.

   terraform plan
   

5. Apply the Terraform execution plan. Terraform takes all of the required actions to modify the tool integration.

   terraform apply
   

Deleting a tool integration by using the console

You can delete tool integrations from your toolchain by using the console. If you delete a tool integration from your toolchain, the deletion cannot be undone.

1. From the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains.
2. On the Toolchains page, click a toolchain to open its Overview page. Alternatively, on the App details page in your app, click the toolchain name.
3. On the tool integration that you want to delete, click the Actions icon > Delete.
4. Confirm by clicking Delete.

Deleting a tool integration with the API

You can delete tool integrations from your toolchain with the API. If you delete a tool integration from your toolchain, the deletion cannot be undone.

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 toolchain where the tool integration exists.

3. Using the ID of the toolchain, look up the ID of the tool integration.

4. Delete the tool integration within the targeted toolchain.

   curl -X DELETE --location --header "Authorization: Bearer {iam_token}" \
     "{base_url}/toolchains/{toolchain_id}/tools/{tool_id}"
   

   const CdToolchainV2 = require('@ibm-cloud/continuous-delivery/cd-toolchain/v2');
   const toolchainService = CdToolchainV2.newInstance();
   ...
   (async() => {
      const response = await toolchainService.deleteTool({
         toolchainId: {toolchain_id},
         toolId: {tool_id}
      });
   })();
   

   import (
       "github.com/IBM/continuous-delivery-go-sdk/cdtoolchainv2"
   )
   ...
   toolchainClientOptions := &cdtoolchainv2.CdToolchainV2Options{}
   toolchainClient, err := cdtoolchainv2.NewCdToolchainV2UsingExternalConfig(toolchainClientOptions)
   deleteToolOptions := toolchainClient.NewDeleteToolOptions({toolchain_id}, {tool_id})
   response, err := toolchainClient.DeleteTool(deleteToolOptions)
   

   from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
   ...
   toolchain_service = CdToolchainV2.new_instance()
   response = toolchain_service.delete_tool(
      toolchain_id = {toolchain_id},
      tool_id = {tool_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();
   DeleteToolOptions deleteToolOptions = new DeleteToolOptions.Builder()
      .toolchainId({toolchain_id})
      .toolId({tool_id})
      .build();
   Response<Void> response = toolchainService.deleteTool(deleteToolOptions).execute();
   

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

Deleting a tool integration with Terraform

You can delete tool integrations from your toolchain with Terraform. If you delete a tool integration from your toolchain, the deletion cannot be undone.

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. Use the Terraform configuration file that you used to create the tool integration. Comment or remove the tool integration resource from the configuration file.

3. Initialize the Terraform CLI.

   terraform init
   

4. Create a Terraform execution plan. This plan summarizes all of the actions that must run to delete the tool integration.

   terraform plan
   

5. Apply the Terraform execution plan. Terraform takes all of the required actions to delete the tool integration.

   terraform apply