@inprod.io/run-changesets

NPM Package for Genesys Cloud CX as Code | InProd Changeset Automation for CI/CD Pipelines

Automate Genesys Cloud configuration deployments in any CI/CD pipeline using InProd changesets. This official open-source NPM package enables Configuration as Code and CX as Code for Genesys Cloud contact centers across GitLab CI, Azure DevOps, Bitbucket Pipelines, CircleCI, Jenkins, GitHub Actions, and custom automation workflows.

What This Package Does

Deploy, validate, and manage Genesys Cloud configurations programmatically through InProd's changeset API. Build custom CI/CD pipelines with full control over deployment logic, validation gates, error handling, and environment promotion workflows for your contact center infrastructure.

Offically Supported CI/CD Platforms:

• GitLab CI/CD See Gitlab Project
• Azure DevOps Pipelines
• Bitbucket Pipelines
• CircleCI
• Jenkins
• GitHub Actions See Marketplace

Learn more: InProd Documentation | Genesys Cloud Platform

Overview

@inprod.io/run-changesets validates and executes InProd changesets as part of your CI/CD pipeline. It is distributed as an npm package invoked via npx, making it compatible with any CI platform that can run Node.js.

Features:

• Validation before execution
• Validate-only mode (for PR/MR pipelines)
• Glob patterns to process multiple changeset files
• Sequential multi-file execution with configurable failure handling
• validate_first strategy: validate all files before executing any
• Variable injection via INPROD_CHANGESET_VARIABLES
• Output artifacts consumable by downstream jobs

Platform Guides

| Platform | Guide | |---|---| | GitLab CI/CD | docs/gitlab.md | | Azure DevOps Pipelines | docs/azure.md | | Bitbucket Pipelines | docs/bitbucket.md | | CircleCI | docs/circleci.md | | Jenkins | docs/jenkins.md |

Environment Variable Reference

All configuration is passed via environment variables. Variables can be set at the pipeline, project, or group level depending on your CI platform.

| Variable | Required | Default | Description | |---|---|---|---| | INPROD_API_KEY | Yes | — | InProd API key for authentication | | INPROD_BASE_URL | Yes | — | Base URL of your InProd instance (e.g. https://app.inprod.io) | | INPROD_CHANGESET_FILE | Yes | — | Path to changeset file(s). Supports glob patterns (e.g. changesets/*.yaml) | | INPROD_ENVIRONMENT | No | "" | Target InProd environment name or ID. If omitted, the changeset's default environment is used | | INPROD_VALIDATE_BEFORE_EXECUTE | No | "true" | Validate the changeset before executing. Set to "false" to skip validation | | INPROD_VALIDATE_ONLY | No | "false" | Only validate; do not execute. Useful for PR/MR pipelines | | INPROD_POLLING_TIMEOUT_MINUTES | No | "10" | Maximum time to wait for async tasks to complete | | INPROD_EXECUTION_STRATEGY | No | "per_file" | "per_file": validate+execute each file in sequence. "validate_first": validate all files, then execute all | | INPROD_FAIL_FAST | No | "false" | Stop processing on first failure when "true" | | INPROD_CHANGESET_VARIABLES | No | "" | Newline-separated KEY=VALUE pairs to inject into changesets at runtime |

Boolean Variables

Boolean variables (INPROD_VALIDATE_BEFORE_EXECUTE, INPROD_VALIDATE_ONLY, INPROD_FAIL_FAST) accept the string values "true" or "false". Any value other than "false" is treated as true for INPROD_VALIDATE_BEFORE_EXECUTE.

Output Files

The package writes two files on exit that downstream jobs can consume:

inprod-results.env

A dotenv-format file with the aggregate status:

INPROD_STATUS=SUCCESS

Possible values: SUCCESS, FAILURE, TIMEOUT, REVOKED, SUBMITTED

inprod-result.json

A JSON array with per-file results:

[
  {
    "file": "queues.yaml",
    "status": "SUCCESS",
    "result": {
      "run_id": 42,
      "changeset_name": "Deploy Queues",
      "environment": { "id": 3, "name": "Production" }
    },
    "error": null
  }
]

Both files are written regardless of whether the job succeeds or fails. See your platform guide for how to publish them as pipeline artifacts or reports.

Variable Injection

Use INPROD_CHANGESET_VARIABLES to inject runtime values into your changeset files. Values are injected into the variable array of the changeset, replacing any existing entries with the same name and preserving mask_value settings.

Format: One KEY=VALUE pair per line. Lines starting with # and blank lines are ignored. Values may contain = characters — only the first = on each line is used as the key/value separator.

Example:

DATABASE_PASSWORD=s3cr3t
API_ENDPOINT=https://api.example.com

See your platform guide for how to pass multi-line values securely.

Debug Logging

Set INPROD_DEBUG=true as an environment variable or pipeline variable to enable verbose debug output, including API request and response details.

Troubleshooting

| Error | Cause | Fix | |---|---|---| | api_key is required and cannot be empty | INPROD_API_KEY not set | Add INPROD_API_KEY as a CI/CD variable in your pipeline settings | | base_url is required and cannot be empty | INPROD_BASE_URL not set | Add INPROD_BASE_URL as a CI/CD variable | | Invalid base_url format | URL is malformed | Ensure INPROD_BASE_URL is a valid URL (e.g. https://app.inprod.io) | | Changeset file not found | Path does not exist in the repository | Check INPROD_CHANGESET_FILE is relative to the repo root | | No files matched the pattern | Glob pattern matched nothing | Verify the glob pattern and that files are committed | | Validation request failed with status 401 | Invalid or expired API key | Regenerate the API key in InProd and update INPROD_API_KEY | | Validation request failed with status 403 | API key lacks permission | Ensure the API key has changeset execute permissions | | Changeset validation failed | Changeset has validation errors | Review the validation errors in the job log | | did not complete within N seconds | Task polling timed out | Increase INPROD_POLLING_TIMEOUT_MINUTES | | Invalid changeset_variables format | A line in INPROD_CHANGESET_VARIABLES has no = | Ensure every non-comment line is KEY=VALUE |

Development

Requirements

• Node.js 18 or later
• npm 8 or later

Setup

git clone https://github.com/inprod/run-changesets.git
cd run-changesets
npm install

Running Tests

npm test

To run tests with coverage:

npm run test:coverage

The test suite uses Jest with fake timers for polling tests. All 107 tests must pass before any changes are merged.

Linting

npm run lint

Project Structure

run-changesets/
├── src/
│   ├── index.js          # Main entry point and all business logic
│   └── index.test.js     # Jest test suite
├── package.json
├── .npmignore
└── CHANGELOG.md

How It Works

The package is a single Node.js script (src/index.js) that:

1. Reads configuration from INPROD_* environment variables
2. Resolves changeset files from the path or glob pattern in INPROD_CHANGESET_FILE
3. For each file, optionally validates it against the InProd API, then executes it
4. Polls the InProd task API until the task completes or times out
5. Writes inprod-results.env and inprod-result.json with the aggregate and per-file results
6. Exits with code 0 on success or 1 on any failure

The package has no CI-platform-specific dependencies — it reads env vars, writes files, and exits, making it compatible with any CI system.

Trademarks: Genesys®, Genesys Cloud™, and the Genesys Cloud logo are trademarks of Genesys. This project is maintained by InProd Solutions and is not an official Genesys product.