IBM Cloud Docs
Working with tool integrations

Working with tool integrations

You can add, update, and delete tool integrations by using the console, with the API, or with Terraform. You can configure tool integrations that support development, deployment, and operations tasks while you create an open toolchain, or you can add and configure tool integrations to customize an existing toolchain.

Understanding tool integrations with IBM Cloud for Financial Services

Although the Continuous Delivery and Toolchain services are designated as IBM Cloud for Financial Services Validated, this designation does not apply to all of the tools that you can integrate into toolchains.

The following tools and tool integrations are not Financial Services Validated:

  • The Git Repos and Issue Tracking component of the Continuous Delivery service.
  • Tool integrations for services in the IBM Cloud catalog that are not designated as Financial Services Validated.
  • Tool integrations for third-party, customer, or tools and services that are not owned and operated by IBM Cloud.

For more information about which tools and tool integrations are Financial Services Validated, see Tool integrations.

For more information about IBM Cloud for Financial Services, see IBM Cloud Framework for Financial Services.

The Continuous Delivery service is Financial Services Validated in the same regions as IBM Cloud for Financial Services. For more information about which multi-zone regions are designated as Financial Services Validated, see Deploy your IBM Cloud resources only to approved multizone regions.

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 hamburger icon, and select DevOps.
  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.

Table 1. Variables for provisioning the tool integration with the API
Variable Description
{base_url} The Toolchain API endpoint URL. For more information about supported values, see Endpoint URL.
{iam_api_key} Your IAM API key.
{iam_token} A valid IAM bearer token.
{tool_name} The name of the tool integration.
{tool_parameters} Unique key-value pairs that represent the parameters to use to create the tool integration. For more information about the supported parameters for each tool integration, see Tool integrations.
{tool_type_id} The unique, short name that represents the type of the tool integration. For a list of supported values, see Tool integrations.
{toolchain_id} The toolchain in which to create the tool integration.

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 hamburger icon, and select DevOps.
  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 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.

Table 2. Variables for updating the tool integration with the API
Variable Description
{base_url} The Toolchain API endpoint URL, for example https://api.us-south.devops.cloud.ibm.com/toolchain/v2. For more information about this endpoint URL, including a list of values, see Endpoint URL.
{iam_api_key} Your IAM API key.
{iam_token} A valid IAM bearer token.
{new_tool_name} The new name of the tool integration.
{new_tool_parameters} The unique key-value pairs that represent the parameters to use to update the tool integration. To view a list of parameters for each tool integration, see Tool integrations.
{tool_id} The ID of the tool integration that you want to update.
{toolchain_id} The ID of the toolchain where the tool integration exists.

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 hamburger icon, and select DevOps.
  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 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.

Table 3. Variables for deleting the tool integration with the API
Variable Description
{base_url} The Toolchain API endpoint URL. For more information about this endpoint URL, including a list of values, see Endpoint URL for a list of values.
{iam_api_key} Your IAM API key.
{iam_token} A valid IAM bearer token.
{tool_id} The ID of the tool integration that you want to delete.
{toolchain_id} The ID of the toolchain where the tool integration exists.

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
    

Tool integrations

The Continuous Delivery service supports several tool integrations.

Although the Continuous Delivery and Toolchain services are designated as IBM Cloud for Financial Services Validated, this designation does not apply to all of the tools that you can integrate into toolchains. The following table indicates which tool integrations and tools are designated as IBM Cloud for Financial Services Validated when they are used with Continuous Delivery toolchains.

If you are using the Continuous Delivery Toolchain API to create a tool integration, set the tool_type_id parameter in the API request to the Tool type ID value for the tool integration that is listed in the following table.

Table 4. Tool integrations available for toolchains on IBM Cloud Public
Tool integration Tool type ID Financial services validated
App Configuration appconfig
Artifactory artifactory
Bitbucket bitbucketgit
Delivery Pipeline pipeline Checkmark icon
Delivery Pipeline Private Worker private_worker
DevOps Insights draservicebroker Checkmark icon
Event Notifications eventnotifications Checkmark icon
Git Repos and Issue Tracking hostedgit
GitHub githubconsolidated
GitLab gitlab
HashiCorp Vault hashicorpvault
Jenkins jenkins
JIRA jira
Key Protect keyprotect
Nexus nexus
Other Tool customtool
PagerDuty pagerduty
Rational Team Concert rationalteamconcert
Sauce Labs saucelabs
Secrets Manager secretsmanager Checkmark icon
Security and Compliance Center security_compliance Checkmark icon
Slack slack
SonarQube sonarqube

If you want to start developing with your source code on IBM Cloud Public, configure the GitHub tool integration or the Git Repos and Issue Tracking tool integration before you configure the Delivery Pipeline.