{"id":27999237,"url":"https://github.com/voximplant/voxengine-ci","last_synced_at":"2025-05-08T22:57:23.889Z","repository":{"id":77510754,"uuid":"484002355","full_name":"voximplant/voxengine-ci","owner":"voximplant","description":"Manage Voximplant Platform `applications`, `rules` and `scenarios` from your own environment","archived":false,"fork":false,"pushed_at":"2025-04-21T09:54:40.000Z","size":650,"stargazers_count":20,"open_issues_count":1,"forks_count":3,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-08T22:57:10.846Z","etag":null,"topics":["devops","voxengine","voximplant"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voximplant.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-04-21T10:14:27.000Z","updated_at":"2025-04-21T09:54:41.000Z","dependencies_parsed_at":"2023-12-13T15:27:12.000Z","dependency_job_id":"e4c75a1a-d1c5-418d-9852-98547b0671d3","html_url":"https://github.com/voximplant/voxengine-ci","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voximplant%2Fvoxengine-ci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voximplant%2Fvoxengine-ci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voximplant%2Fvoxengine-ci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voximplant%2Fvoxengine-ci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voximplant","download_url":"https://codeload.github.com/voximplant/voxengine-ci/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253160791,"owners_count":21863627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["devops","voxengine","voximplant"],"created_at":"2025-05-08T22:57:23.161Z","updated_at":"2025-05-08T22:57:23.881Z","avatar_url":"https://github.com/voximplant.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VOXENGINE-CI\n\nManage [Voximplant Platform](https://voximplant.com/platform) `applications`, `rules`, and `scenarios` from your own environment using [@voximplant/apiclient-nodejs](https://www.npmjs.com/package/@voximplant/apiclient-nodejs) under the hood.\n\n---\n\n## Installation\n\n```shell\n  npm i @voximplant/voxengine-ci\n```\n\n---\n\n## Service account\n\nGo to the [Service accounts](https://manage.voximplant.com/settings/service_accounts) section of the control panel and generate a file with your account credentials. Learn more about service accounts [here](https://voximplant.com/docs/howtos/integration/httpapi/auth)\n\n## Configuration\n\nCreate a `.env` file in the root directory of your project and add environment-specific variables:\n\n```shell\n  VOX_CI_CREDENTIALS=/path/to/the/vox_ci_credentials.json\n  VOX_CI_ROOT_PATH=/path/to/the/voxengine_ci_source_files_directory\n```\n\n- VOX_CI_CREDENTIALS - path to your `JSON` credentials file (`vox_ci_credentials.json` by default)\n- VOX_CI_ROOT_PATH - path to the directory where the `vox` files will be located (`voxfiles` by default)\n\nCreating a .env file is not necessary if you move the file with credentials to your project folder, and it has a default name – `vox_ci_credentials.json`.\nThe folder with the files created after initialization will be placed in your project folder as well and will be named `voxfiles` unless you decide to create a .env variable and specify something different there.\n\n---\n\n## Usage\n\nFirst, initialize the project (download all files and metadata from your VoxImplant account). When all the files have been successfully downloaded from the platform, you can modify them and upload them back to the platform. Read the __scripts__ paragraph to learn more.\n\nRead the full [Voxengine CI](https://voximplant.com/docs/guides/voxengine/ci) guide for more details.\n\n### Creating a new application\n\nCreate an `application.config.json` file in the `/path/to/the/voxengine_ci_source_files_directory/applications/your-application-name.your-account-name.voximplant.com/` directory, where `/path/to/the/voxengine_ci_source_files_directory` is created with the `npx voxengine-ci init` command (you specified this path in the `VOX_CI_ROOT_PATH` env variable). Then, add the following config to this file:\n\n```shell\n  {\"applicationName\":\"your-application-name.your-account-name.voximplant.com\"}\n```\n\nIn the same directory, create a `rules.config.json` file with this config:\n\n```shell\n  [\n    { \"ruleName\":\"first-rule\",\"scenarios\":[\"first-scenario\"],\"rulePattern\":\"string-with-regexp\" },\n    { \"ruleName\":\"second-rule\",\"scenarios\":[\"second-scenario\"],\"rulePattern\":\"string-with-regexp\" }\n  ]\n```\n\nwhere `first-rule` and `second-rule` are the names of your rules, `first-scenario` and `second-scenario` are the names of your scenarios (you can change them in the `/scenarios/src` directory), `string-with-regexp` is a regular expression to validate caller IDs in inbound calls (\".*\" by default).\n\nYou can modify existing scenarios and create new ones ONLY in the `/voxfiles/scenarios/src` directory. Only the scenarios having their names specified in `rules.config.json` will be uploaded to the platform. The scenario file names should match the *.voxengine.{js,ts} pattern. These are the files where you write the scenarios code.\n\nWhen configs and scenarios are ready, run\n\n```shell\n  npx voxengine-ci upload --application-name your-application-name\n```\n\nto upload this new application with all rules and scenarios to the platform.\n\nYou can also use the `--dry-run` flag in this and the following command to build the project locally without uploading changes to the platform.\n\n## Modifying an application and its rules\n\nWhen an application is uploaded to the platform, you can add/modify rules (configure them in `rules.config.json`) and scenarios (in /scenarios/src) and run the previous command to upload the changes. If you specify a rule name or rule id in the command, only the scenarios attached to this rule will be uploaded to the platform:\n\n```shell\n  npx voxengine-ci upload --application-name your-application-name --rule-name your-rule-name\n```\n\nIt works either when you upload a new rule or when you modify an existing one.\n\nIf you modify an existing application or existing rule, you can specify `--application-id` and `--rule-id` instead of `-application-name` and `--rule-name`:\n\n```shell\n  npx voxengine-ci upload --application-id your-application-id --rule-id your-rule-id\n```\n\nWhen you change the name of an application, scenario, or rule using Voxengine CI, a new app, scenario, and rule with the same content is created on the platform. The old one is not deleted or changed due to the Voxengine CI inner logic.\n\nYou can modify these old apps, scenarios, and rules only from the platform without sharing the changes with Voxengine CI (NOT RECOMMENDED) unless you run `npx voxengine-ci init --force` to make your local and remote versions consistent.\n\n---\n\n## Scripts\n\n### Initialize the project\n\n```shell\n  npx voxengine-ci init\n```\n\n### Initialize the project from scratch, deleting all existing files and configurations\n\n```shell\n  npx voxengine-ci init --force\n```\n\n### Build application scenarios (by specifying _application-name_) for ALL application rules without uploading to the platform\n\n```shell\n  npx voxengine-ci upload --application-name your_application_name --dry-run\n```\n\n### Build application scenarios (by specifying _rule-name_) for a specified application rule without uploading to the platform\n\n```shell\n  npx voxengine-ci upload --application-name your_application_name --rule-name your_rule_name --dry-run\n```\n\n### Build and upload application scenarios (by specifying _application-name_) for ALL application rules\n\n```shell\n  npx voxengine-ci upload --application-name your_application_name\n```\n\n### Build and upload application scenarios (by specifying _application-name_ and _rule-name_) for a specified application rule\n\n```shell\n  npx voxengine-ci upload --application-name your_application_name --rule-name your_rule_name\n```\n\n### Build and __force__ upload application scenarios (by specifying _application-name_) for ALL application rules\n\nThis command is useful if scenarios have been modified on the platform without using voxengine-ci and you are going to overwrite those changes.\n\n```shell\n  npx voxengine-ci upload --application-name your_application_name --force\n```\n\n### Build and __force__ upload application scenarios (by specifying _rule-name_) for a specified rule\n\nThis command is useful if scenarios have been modified on the platform without using voxengine-ci and you are going to overwrite those changes.\n\n```shell\n  npx voxengine-ci upload --application-name your_application_name --rule-name your_rule-name --force\n```\n\n`--application-id` and `--rule-id` flags can be used instead of `--application-name` and `--rule-name` for the `npx voxengine-ci upload` command when you modify an existing application and rules.\n\n---\n\n## CI/CD templates\n\n### GitLab\n\nInclude a template in your CI/CD job:\n\n```yml\n  include:\n    - remote: 'https://raw.githubusercontent.com/voximplant/voxengine-ci/main/ci-cd-templates/.gitlab.yml'\n```\n\nDefine env variables:\n\n- `VOX_CI_CREDENTIALS` – path to your `JSON` credentials file (`vox_ci_credentials.json` by default)\n- `VOX_CI_CREDENTIALS_CONTENT` – `vox_ci_credentials.json` file contents in the `JSON` format\n\nUse the `extends` keyword to reuse the `.voxengine-ci` configuration sections from the template:\n\n```yml\nyour-job:\n  extends:\n    - .voxengine-ci\n  script:\n    - your-script-part-one\n    - your-script-part-two\n    - etc.\n```\n\nYou can customize your script using the following example:\n\n```yml\nyour-job:\n  extends:\n    - .voxengine-ci\n  variables:\n    VOX_CI_CREDENTIALS: $SECRET_FILE_PATH\n    VOX_CI_CREDENTIALS_CONTENT: $SECRET_FILE_CONTENT\n  dependencies:\n    - build\n  when: manual\n  only:\n    - master\n  tags:\n    - docker\n  script:\n    - npx voxengine-ci upload --application-id 123456\n    - npx voxengine-ci upload --application-name my_first_application\n    - npx voxengine-ci upload --application-name my_first_application --rule-name my_second_rule --dry-run\n```\n\n### GitHub\n\nCopy the `https://github.com/voximplant/voxengine-ci/blob/main/ci-cd-templates/.github.yml` YAML file contents to your repository at `.github/workflows/any_file_name.yml`.\n\nDefine the _GitHub Actions secrets_ in the `settings/secrets/actions` section of your GitHub project:\n\n- `VOX_CI_CREDENTIALS` – path to your `JSON` credentials file (`vox_ci_credentials.json` by default)\n- `VOX_CI_CREDENTIALS_CONTENT` - `vox_ci_credentials.json` file contents in the `base64` format\n\n\u003e __NOTE:__ since GitHub has restrictions on passing _Actions secrets_ in the `JSON` format, you need to __base64-encode__ the value before assigning it to the `VOX_CI_CREDENTIALS_CONTENT` variable\n\nYou can customize your script using the following example:\n\n```yml\nname: voxengine-ci\n\non: workflow_dispatch\n\njobs:\n  your-job:\n    runs-on: ubuntu-latest\n    needs: [ build ]\n    steps:\n      - uses: actions/checkout@v3\n      - name: Setup Node.js\n        uses: actions/setup-node@v3\n        with:\n          node-version: '20'\n          check-latest: true\n      - name: Install voxengine-ci\n        run: npm ci\n      - name: Prepare credentials\n        run: echo \"${{ env.VOX_CI_CREDENTIALS_CONTENT }}\" | base64 --decode \u003e ${{ env.VOX_CI_CREDENTIALS }}\n        env:\n          VOX_CI_CREDENTIALS: ${{ secrets.SECRET_FILE_PATH }}\n          VOX_CI_CREDENTIALS_CONTENT: ${{ secrets.SECRET_FILE_CONTENT }}\n      - name: Run voxengine-ci scripts\n        run: |\n          npx voxengine-ci upload --application-id 123456\n          npx voxengine-ci upload --application-name my_first_application\n          npx voxengine-ci upload --application-name my_first_application --rule-name my_second_rule --dry-run\n```\n\n### Jenkins\n\nFirst, install all necessary plugins:\n\n- NodeJS plugin. After the plugin has been installed, click __Add NodeJS__ in the __NodeJS installations__ section (in Global Tool Configuration) and specify a name (e.g. \"nodejsinstallation\" - this name will be used in the __Build environment__ section).\n\n- Git plugin\n\n- Credentials Binding plugin\n\n- Pipeline plugin (for using Jenkinsfile)\n\n#### Creating a job using the \"Freestyle project\" Item\n\nCreate a new Item and select __Freestyle project__.\n\nIn __Source code management__, choose the __Git__ option and specify the repository URL and credentials. If there are no SSH credentials in Jenkins yet, generate them and add a private key of the __SSH Username with private key__ type (choose the __Enter directly__ option in the __Private key__ section), and add a public key in your git account (__SSH keys__ section).\n\nIn __Build environment__, choose the __Use secret text(s) or file(s)__ option, specify the \"VOX_CI_CREDENTIALS\" name for the corresponding variable and add the \"vox_ci_credentials.json\" file of the __Secret file__ type with credentials of your vox account.\n\nCheck __Provide Node \u0026 npm bin/ folder to PATH__ in the __Build environment__ section and specify the name of the NodeJS installation (\"nodejsinstallation\" in our example).\n\nIn the __Build__ section, select __Execute shell__ in the __Build step__ dropdown list and add the following script:\n\n```shell\nnpm ci\nnpx voxengine-ci upload --application-name my-application\n```\n\nThe job is ready to run.\n\n#### Using Jenkinsfile\n\nIn your project repository, add Jenkinsfile:\n\n```shell\npipeline {\n    agent any\n    tools {nodejs \"nodejsinstallation\"} // name of your NodeJS installation\n    stages {\n        stage('Before-publish') {\n            steps {\n                sh \"npm ci\"\n            }\n        }\n        stage('Publish') {\n            steps {\n                sh \"npx voxengine-ci upload --application-name test\" // your voxengine-ci script\n            }\n        }\n    }\n}\n```\n\nCreate the __Pipeline__ Item.\n\nSelect __Pipeline script from SCM__ in the __Pipeline__ section.\n\nSelect __Git__ from the __SCM__ dropdown list, set your repository URL using SSH, and choose credentials. If you do not have credentials yet, click __Add__ and select the __SSH Username with private key__ type. Then add a private key (in the __Private key__ section, choose __Enter directly__) and a public key in your git account (__SSH keys__).\n\nSpecify __Jenkinsfile__ in __Script Path__.\n\nPipeline is ready!\n\n## Instruments\n\n[node.js](https://nodejs.org/en/)  \n[typescript](https://www.typescriptlang.org/)  \n[dotenv](https://www.npmjs.com/package/dotenv)  \n[@voximplant/apiclient-nodejs](https://www.npmjs.com/package/@voximplant/apiclient-nodejs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoximplant%2Fvoxengine-ci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoximplant%2Fvoxengine-ci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoximplant%2Fvoxengine-ci/lists"}