# IBM Cloud Continuous Delivery Node.js SDK

[![Build](https://github.com/IBM/continuous-delivery-node-sdk/actions/workflows/release.yml/badge.svg)](https://github.com/IBM/continuous-delivery-node-sdk/actions/workflows/release.yml)
[![npm](https://img.shields.io/npm/v/@ibm-cloud/continuous-delivery)](https://npmjs.com/package/@ibm-cloud/continuous-delivery)
[![Release](https://img.shields.io/github/v/release/IBM/continuous-delivery-node-sdk)](https://github.com/IBM/continuous-delivery-node-sdk/releases/latest)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)

The Node.js client library to interact with the [IBM Cloud Continuous Delivery Toolchain and Tekton Pipeline APIs](https://cloud.ibm.com/docs?tab=api-docs&category=devops).

## Table of Contents

<!--
  The TOC below is generated using the `markdown-toc` node package.

      https://github.com/jonschlinkert/markdown-toc

  You should regenerate the TOC after making changes to this file.

      npx markdown-toc -i README.md
  -->

<!-- toc -->

- [IBM Cloud Continuous Delivery Node.js SDK](#ibm-cloud-continuous-delivery-nodejs-sdk)
  - [Table of Contents](#table-of-contents)
  - [Overview](#overview)
  - [Migration](#migration)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
  - [Using the SDK](#using-the-sdk)
  - [Questions](#questions)
  - [Issues](#issues)
  - [Open source @ IBM](#open-source--ibm)
  - [Contributing](#contributing)
  - [License](#license)

<!-- tocstop -->

<!-- --------------------------------------------------------------- -->
## Overview

The IBM Cloud Continuous Delivery Node.js SDK allows developers to programmatically interact with the following
IBM Cloud services:

Service Name | Import Path
--- | ---
[Toolchain API](https://cloud.ibm.com/apidocs/toolchain?code=node) | @ibm-cloud/continuous-delivery/cd-toolchain/v2
[Tekton Pipeline API](https://cloud.ibm.com/apidocs/tekton-pipeline?code=node) | @ibm-cloud/continuous-delivery/cd-tektonpipeline/v2

Table 1. IBM Cloud services

<!-- --------------------------------------------------------------- -->
## Migration

`ibm-continuous-delivery` package has been deprecated!
The IBM Continuous Delivery Node SDK is now available as `@ibm-cloud/continuous-delivery`.

To migrate to the new package, you can use the commands listed below:

```sh
npm uninstall ibm-continuous-delivery
npm install @ibm-cloud/continuous-delivery
```

You will also need to modify any references to the old package `ibm-continuous-delivery` within import/require statements so they reflect the new package `@ibm-cloud/continuous-delivery`.  Here is an example:

```javascript
// 'require' statements that reflect the old package name:
const CdToolchainV2 = require("ibm-continuous-delivery/cd-toolchain/v2");
const CdTektonPipelineV2 = require("ibm-continuous-delivery/cd-tekton-pipeline/v2");

// Modify this to reflect the new package name:
const CdToolchainV2 = require("@ibm-cloud/continuous-delivery/cd-toolchain/v2");
const CdTektonPipelineV2 = require("@ibm-cloud/continuous-delivery/cd-tekton-pipeline/v2");
```

## Prerequisites

- You need an [IBM Cloud][ibm-cloud-onboarding] account.
- **Node.js >=22**: This SDK is tested with Node.js versions 22 and up. It may work on previous versions but this is not officially supported.

[ibm-cloud-onboarding]: http://cloud.ibm.com/registration

## Installation

```sh
npm install @ibm-cloud/continuous-delivery
```

## Using the SDK

For general SDK usage information, see [IBM Cloud SDK Common README](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.md).

## Development

### Running Integration Tests

Integration tests run against live IBM Cloud services and require proper configuration. To run integration tests locally or in CI/CD:

#### Required GitHub Secrets

Configure the following secrets in your GitHub repository (Settings → Secrets and variables → Actions):

- `CLOUD_API_KEY`: IBM Cloud API key with permissions to create and manage Continuous Delivery resources

#### Required GitHub Variables

Configure the following variables in your GitHub repository (Settings → Secrets and variables → Actions):

**For CD Toolchain Service:**
- `CD_TOOLCHAIN_URL`: Service endpoint URL (e.g., `https://api.us-south.devops.cloud.ibm.com/toolchain/v2`)
- `CD_TOOLCHAIN_AUTH_TYPE`: Authentication type (typically `iam`)
- `CD_TOOLCHAIN_EVENT_NOTIFICATIONS_SERVICE_CRN`: Event Notifications service CRN for toolchain events
- `CD_TOOLCHAIN_RESOURCE_GROUP_ID`: IBM Cloud resource group ID where resources will be created

**For CD Tekton Pipeline Service:**
- `CD_TEKTON_PIPELINE_URL`: Service endpoint URL (e.g., `https://api.us-south.devops.cloud.ibm.com/pipeline/v2`)
- `CD_TEKTON_PIPELINE_AUTH_TYPE`: Authentication type (typically `iam`)
- `CD_TEKTON_PIPELINE_RESOURCE_GROUP_ID`: IBM Cloud resource group ID where resources will be created

#### Local Development

For local integration testing, create the following environment files in the project root:

**cd_toolchain_v2.env:**
```bash
CD_TOOLCHAIN_APIKEY=<your-ibm-cloud-api-key>
CD_TOOLCHAIN_URL=https://api.us-south.devops.cloud.ibm.com/toolchain/v2
CD_TOOLCHAIN_AUTH_TYPE=iam
CD_TOOLCHAIN_EVENT_NOTIFICATIONS_SERVICE_CRN=<your-event-notifications-crn>
CD_TOOLCHAIN_RESOURCE_GROUP_ID=<your-resource-group-id>
```

**cd_tekton_pipeline_v2.env:**
```bash
CD_TEKTON_PIPELINE_URL=https://api.us-south.devops.cloud.ibm.com/pipeline/v2
CD_TEKTON_PIPELINE_AUTH_TYPE=iam
CD_TEKTON_PIPELINE_APIKEY=<your-ibm-cloud-api-key>
CD_TEKTON_PIPELINE_RESOURCE_GROUP_ID=<your-resource-group-id>
CD_TOOLCHAIN_URL=https://api.us-south.devops.cloud.ibm.com/toolchain/v2
CD_TOOLCHAIN_AUTH_TYPE=iam
CD_TOOLCHAIN_APIKEY=<your-ibm-cloud-api-key>
CD_TOOLCHAIN_RESOURCE_GROUP_ID=<your-resource-group-id>
```

**Note:** These `.env` files are gitignored and should never be committed to version control.

#### Running Tests

```bash
# Run unit tests only
npm run test-unit

# Run integration tests (requires .env files)
npm run test-integration

# Run all tests
npm test
```

#### CI/CD Integration Tests

Integration tests run automatically on pull requests. To skip integration tests in a manual workflow run:

1. Go to Actions → pull-request workflow
2. Click "Run workflow"
3. Check "Skip integration tests"
4. Click "Run workflow"

## Issues

If you encounter an issue with the SDK, you are welcome to submit
a [bug report](https://github.com/IBM/continuous-delivery-node-sdk/issues).
Before that, please search for similar issues. It's possible someone has
already encountered this issue.

## Open source @ IBM

Find more open source projects on the [IBM Github Page](http://ibm.github.io/)

## Contributing

See [CONTRIBUTING](CONTRIBUTING.md).

## License

This project is released under the Apache 2.0 license.
The license's full text can be found in
[LICENSE](LICENSE).