@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.