Introduction

IBM Cloud® Continuous Delivery Tekton pipelines leverage the open source Tekton Pipelines project to provide continuous integration and continuous deployment capabilities within Kubernetes clusters.

Tekton Pipelines is an open source project that you can use to configure and run continuous integration and continuous deployment pipelines within a Kubernetes cluster. Tekton pipelines are defined in yaml files, which are typically stored in a Git repository (repo).

For more information about our Continuous Delivery Tekton pipeline, see Working with Tekton pipelines.

Installing the Node SDK.

npm install @ibm-cloud/continuous-delivery

For more information, view the project on GitHub: https://github.com/IBM/continuous-delivery-node-sdk

Installing the Python SDK.

pip install "ibm-continuous-delivery"

For more information, view the project on GitHub: https://github.com/IBM/continuous-delivery-python-sdk

Installing the Go SDK.

Go modules (recommended): Add the following import in your code and then run go mod tidy.

import (
  "github.com/IBM/continuous-delivery-go-sdk/v2/cdtektonpipelinev2"
)

Using Go get:

go get -u github.com/IBM/continuous-delivery-go-sdk/v2/cdtektonpipelinev2

For more information, view the project on GitHub: https://github.com/IBM/continuous-delivery-go-sdk

Installing the Java SDK.

Maven example:

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>cd-tekton-pileline</artifactId>
    <version>2.0.1</version>
</dependency>

Gradle example:

compile 'com.ibm.cloud:cd-tekton-pileline:2.0.1'

For more information, view the project on GitHub: https://github.com/IBM/continuous-delivery-java-sdk. See also Using the SDK.

Endpoint URL

The Continuous Delivery Tekton pipeline API uses the regional endpoints. When you call the API, add the path for each method to form the complete API endpoint for your requests:

Continuous Delivery will be discontinued in the following regions on 12 February 2027: au-syd, ca-mon, ca-tor, us-east. On 12 June 2026, customers will no longer be able to create new resources in the affected regions. However, if a region has no active usage, the region may be discontinued earlier and stop accepting new instances. Learn more.

Dallas: https://api.us-south.devops.cloud.ibm.com/pipeline/v2
London: https://api.eu-gb.devops.cloud.ibm.com/pipeline/v2
Frankfurt: https://api.eu-de.devops.cloud.ibm.com/pipeline/v2
Tokyo: https://api.jp-tok.devops.cloud.ibm.com/pipeline/v2
São Paulo: https://api.br-sao.devops.cloud.ibm.com/pipeline/v2
Montreal (deprecated, limited availability region): https://api.ca-mon.devops.cloud.ibm.com/pipeline/v2
Sydney (deprecated): https://api.au-syd.devops.cloud.ibm.com/pipeline/v2
Toronto (deprecated): https://api.ca-tor.devops.cloud.ibm.com/pipeline/v2
Washington DC (deprecated): https://api.us-east.devops.cloud.ibm.com/pipeline/v2

Note: The following regions have been discontinued and are no longer available:

Osaka (jp-osa)
Madrid (eu-es)

Authentication

Authentication to the Tekton pipeline V2 API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token determines the actions that a user has access to when they use the API.

To get an access token, use an API key. To get your API key, access the IBM Cloud API keys page and create your API key. You can use this key to generate your IAM access (bearer) token. To use the Tekton API, add your valid IAM token to the HTTP Authorization request header, for example, -H "Authorization: Bearer <IAM_TOKEN_VALUE>".

Example request to generate an access token, where <API_KEY> is your IBM Cloud API Key.:

curl -X POST \
  'https://iam.cloud.ibm.com/identity/token' \
  -H 'Content-Type:application/x-www-form-urlencoded' \
  -H 'Accept:application/json' \
  -d 'grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=<API_KEY>'

From the result of this curl command, take the access_token value and use it in place of <IAM_TOKEN_VALUE> in the curl command below to authenticate into the Tekton API:

curl -L --request GET \
  'https://api.us-south.devops.cloud.ibm.com/pipeline/v2/tekton_pipelines/<PIPELINE_ID>' \
  --header 'Authorization: Bearer <IAM_TOKEN_VALUE>'

Or export the returned access_token value as an environment variable and use that variable in the curl command:

export IAMTOKEN="<access_token_value>"
curl -L --request GET \
  'https://api.us-south.devops.cloud.ibm.com/pipeline/v2/tekton_pipelines/<PIPELINE_ID>' \
  --header 'Authorization: Bearer ${IAMTOKEN}'

Setting client options through environment variables

Example environment variables, where <API_KEY> is an IAM API key.

export CD_TEKTON_PIPELINE_URL=https://api.us-south.devops.cloud.ibm.com/pipeline/v2
export CD_TEKTON_PIPELINE_AUTHTYPE=iam
export CD_TEKTON_PIPELINE_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/continuous-delivery-go-sdk/v2/cdtektonpipelinev2"
}
...
cdTektonPipelineServiceOptions := &cdtektonpipelinev2.CdTektonPipelineV2Options{}
cdTektonPipelineService, err = cdtektonpipelinev2.NewCdTektonPipelineV2UsingExternalConfig(cdTektonPipelineServiceOptions)

Setting client options programmatically

Construct the service client programmatically, where <API_KEY> is your hardcoded IAM API key.

const CdTektonPipelineV2 = require('@ibm-cloud/continuous-delivery/cd-tekton-pipeline/v2');
const { IamAuthenticator } = require('@ibm-cloud/continuous-delivery/auth');

// Create an IAM authenticator.
const authenticator = new IamAuthenticator({
  apikey: '<API_KEY>'
});

// Construct the service client.
const tektonService = new CdTektonPipelineV2({
  authenticator,                                                      // required
  serviceUrl: 'https://api.us-south.devops.cloud.ibm.com/pipeline/v2' // optional
});

Setting client options through external configuration

Example environment variables, where <API_KEY> is an IAM API key.

export CD_TEKTON_PIPELINE_URL=https://api.us-south.devops.cloud.ibm.com/pipeline/v2
export CD_TEKTON_PIPELINE_AUTHTYPE=iam
export CD_TEKTON_PIPELINE_APIKEY=<API_KEY>

Construct the service client using external configuration. CdTektonPipelineV2.newInstance() initializes the client with the environment variables, using them for subsequent authentication.

const CdTektonPipelineV2 = require('@ibm-cloud/continuous-delivery/cd-tekton-pipeline/v2');
const tektonService = CdTektonPipelineV2.newInstance();

Setting client options through external configuration

Example environment variables, where <API_KEY> is an IAM API key.

export CD_TEKTON_PIPELINE_URL=https://api.us-south.devops.cloud.ibm.com/pipeline/v2
export CD_TEKTON_PIPELINE_AUTHTYPE=iam
export CD_TEKTON_PIPELINE_APIKEY=<API_KEY>

Example of constructing the service client

from ibm_continuous_delivery.cd_tekton_pipeline_v2 import CdTektonPipelineV2
service = CdTektonPipelineV2.new_instance()

Setting client options programmatically

Construct the service client programmatically, where <API_KEY> is your hardcoded IAM API key.

import com.ibm.cloud.continuous_delivery.cd_tekton_pipeline.v2.CdTektonPipeline;
import com.ibm.cloud.sdk.core.security.Authenticator;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;
...
Authenticator authenticator = new IamAuthenticator.Builder()
  .apikey("<API_KEY>")
  .build();
CdTektonPipeline pipelineSvc = new CdTektonPipeline(CdTektonPipeline.DEFAULT_SERVICE_NAME, authenticator);

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

| HTTP Error Code | Description | Recovery | |-----------------|-----------------------|-----------------------------------------------------------------------------| | 200 | Success | The request was successful. | | 400 | Bad Request | The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request. | | 401 | Unauthorized | You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions. | | 404 | Not Found | The requested resource could not be found or The supplied authentication is not authorized to access '{namespace}'. | | 408 | Request Timeout | The connection to the server timed out. Wait a few minutes, then try again. | | 409 | Conflict | The entity is already in the requested state. | | 500 | Internal Server Error | offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again. |

ErrorResponse

| Name | Type | Description | |----------------- | --------|--------------------------------------------------------| | code | Integer | HTTP error code. | | error | String | Human-readable error string, like 'Invalid image file'.|

Versioning

All Tekton pipeline API requests are prefixed with a segment that represents the API version. The latest version of the Tekton pipeline API is v2. The versions of individual components of Continuous Delivery, such as toolchain and pipeline, may change independently of each other.

Pagination

Some API requests may return multiple results. To avoid performance problems, these results are returned one page at a time, with a limited number of results in each page. GET requests for the /tekton_pipelines/{pipeline_id}/pipeline_runs resource use pagination.

The fields first, previous, next, and last are included in the collection response as needed, depending on the number of the results. The href property for these fields contains a URL reference to the appropriate page of results from the collection resource. Pagination is token based, where the response will return results from the beginning of the collection and will provide the appropriate next link, which contains a start token, to traverse through the rest of the collection.

The default page size is 50 items, and the maximum size is 100 items. To control the page size, use the limit query parameter.

Rate limiting

Rate limits for API requests are enforced on this service. If the number of requests reaches the request limit within the specified time window, no further requests are accepted until after the time window. Clients that are blocked by rate limited should wait and try the request again later.

An HTTP status code of 429 indicates that the rate limit has been exceeded.

Glossary

Tekton Pipeline: Continuous Delivery Tekton pipeline
Pipeline run: Continuous Delivery Tekton pipeline run
PipelineRun: Pure Tekton pipeline PipelineRuns

Related APIs

Toolchain

Continuous Delivery Tekton Pipeline v2 | IBM Cloud API Docs