Using toolchains

Open toolchains are available on IBM Cloud®. You can use a toolchain to be productive in your daily development, deployment, and operations work. After you set up a toolchain, you can add, delete, or configure tool integrations and manage access to the toolchain. For more information about working with tool integrations, see Working with tool integrations.

Managing access to toolchains

You can use the Identity and Access Management (IAM) service to manage user access to toolchains in resource groups. For more information about managing access control with IAM, see Managing user access to toolchains in resource groups.

Users with access to toolchains might be counted as authorized users of the IBM Cloud® Continuous Delivery service. For more information about how authorized users are counted, see Plan limitations and usage.

Organizing toolchains

You can add tags to your toolchains to organize them and easily find them later. A tag is a label that you assign to a toolchain for easy filtering of toolchains in your toolchains list.

From the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains.
On the Toolchains page, locate the toolchain that you want to add a tag to and click Add tags.
Enter a name for the tag that you want to add to the toolchain. You can add multiple tags, which are separated by commas.
Click Save.

For more information about tags, see Working with tags.

Viewing toolchain connections to apps, clusters, and services

You can view your toolchain's connections to Kubernetes clusters and services.

From the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains.
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.
Select the Connections tab, and select the app, cluster, or service that you want to view.

Deleting a toolchain

You can delete a toolchain. When you delete a toolchain, all of the tool integrations that belong to that toolchain are also deleted. The deletion cannot be undone.

When you delete a Delivery Pipeline tool integration, the associated Delivery Pipeline is also deleted.

When you delete a GitHub or Git Repos and Issue Tracking tool integration, the associated repo is not deleted from GitHub or Git Repos and Issue Tracking. You must manually remove the repo.

Deleting a toolchain by using the console

From the IBM Cloud console, click the Menu icon > Platform Automation > Toolchains.
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.
Click the Actions menu and select Delete. Deleting a toolchain removes all of its tool integrations, which might delete resources that are managed by those integrations.
Confirm the deletion by typing the name of the toolchain and clicking Delete.

Deleting a toolchain from the CLI (Beta)

Log in to IBM Cloud by using the IBM Cloud CLI.
```
ibmcloud login
```
If the login fails, run the ibmcloud login --sso command to try again. The --sso parameter is required when you log in with a federated ID. If you use this option, go to the link that is listed in the CLI output to generate a one-time passcode.
Optional. List all of the toolchains in the targeted account, region, and resource group to identify the instance that you want to delete.
```
ibmcloud dev toolchains
```
Delete a toolchain by running the ibmcloud dev toolchain-delete command.
```
ibmcloud dev toolchain-delete TOOLCHAIN-NAME
```

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

Variables for deleting the toolchain from the CLI
Variable	Description
`TOOLCHAIN_NAME`	The name of the toolchain that you want to delete.

Deleting a toolchain with the API

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}
```

Delete the toolchain that you want to remove.

curl -X DELETE \
  "{base_url}/toolchains/{toolchain_id}" \
  -H 'Authorization: Bearer {token}'

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

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

from ibm_continuous_delivery.cd_toolchain_v2 import CdToolchainV2
...
toolchain_service = CdToolchainV2.new_instance()
response = toolchain_service.delete_toolchain(
   toolchain_id = toolchain_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();
DeleteToolchainOptions deleteToolchainOptions = new DeleteToolchainOptions.Builder()
   .toolchainId({toolchain_id})
   .build();
Response<Void> response = toolchainService.deleteToolchain(deleteToolchainOptions).execute();

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

Variables for deleting the toolchain 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.
`{token}`	A valid IAM bearer token.
`{toolchain_id}`	The ID of the toolchain that you want to delete.

Deleting a toolchain with Terraform

Locate the Terraform file (for example, main.tf) that contains the resource block for the existing toolchain. For more information about using Terraform with toolchains, see Creating a toolchain with Terraform.

The resource in the following example describes an existing toolchain.
```
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
}
```
Remove the resource block from your Terraform file.
Initialize the Terraform CLI.
```
terraform init
```
Create a Terraform execution plan. This plan summarizes all of the actions that must run to delete the toolchain.
```
terraform plan
```
Apply the Terraform execution plan. Terraform takes all of the required actions to delete the toolchain.
```
terraform apply
```

Managing alternative toolchains in different regions

You can define your toolchain by using Terraform Configuration Language, and then apply and maintain your toolchain definition in two regions: a primary region with active pipelines, and an alternative region with idle pipelines. If you use Git Repos and Issue Tracking, you can also mirror your Git repos from the primary region to the alternative region. Maintaining primary and alternative toolchains and Git repos provides faster failover and redundancy. It also ensures smooth operation if issues arise in the primary region. By codifying your toolchain in Terraform, you can update your toolchain and apply the changes to both regions.

For more information about using Terraform, see Setting up Terraform for Continuous Delivery.