polyci

Generates GitLab CI pipelines for monorepos. Discovers modules under a root directory, creates per-module build, test, release, publish, and deploy jobs, and wires them with conventional-commit-based versioning via semalease.

Installation

npm install
npm run build

Or use via npx polyci when the package is published.

Usage

npx polyci [output] [options]

Example (typical GitLab CI setup):

npx polyci --modules-root modules polyci-pipeline.yml

Options:

| Option | Description | Default | |--------|-------------|---------| | -o, --output <path> | Output pipeline file path | — | | --modules-root <path> | Root directory to scan for modules | ./modules | | --main-branch <name> | Primary branch for release tagging | main | | --version-template <template> | Version template for main branch; placeholders: {version}, {branch}, {increment} | {version} | | --branch-version-template <template> | Version template for non-main branches | {version}-{branch}-{increment} | | --tag-template <template> | Tag template; placeholders: {module}, {version} | {module}-v{version} | | --tag-pattern <pattern> | Tag regex for main branch (passed to semalease) | ^$PLI_MODULE_NAME-v(?<version>...) | | --branch-tag-pattern <pattern> | Tag regex for non-main branches (with ?<increment>) | — | | --cwd <path> | Working directory | current directory |

Description

If there is no new version, publish and deploy finish successfuly doing nothing.

Requirements

• POLYCI_TOKEN — GitLab OAuth token for pushing tags; must be defined in GitLab CI/CD variables and available to jobs that run the release stage.
• Module build — Each module must support npm run build and produce output in ./dist.

For docker-service deploy type: a Docker host with Traefik 3.

PLI_ variables

Jobs receive module context via PLI_-prefixed variables, written to polyci.env and sourced between stages.

| Variable | Set by | Description | |----------|--------|-------------| | PLI_MODULE_NAME | build | Module name (directory name under modules-root) | | PLI_MODULE_PATH | build | Path to the module directory | | PLI_MODULE_TYPE | build | Module type (e.g. node-vite, node-express, docker-service) | | PLI_MODULE_VERSION | release | Version string; set only when there is a new release | | PLI_MODULE_TAG | release | Git tag for the module (e.g. module-name-v1.0.0) | | PLI_PACKAGE_NAME | deploy scripts | name from package.json (used by node-docker deploy) | | PLI_INSTANCE_CONTAINER | deploy scripts | {PLI_PACKAGE_NAME}-{CI_COMMIT_BRANCH} for docker-service | | PLI_INSTANCE_DOMAIN | deploy scripts | Domain(s) from package.json; branch-prefixed for non-main |

Recommendations

• Do not modify the built-in module types (node-vite, node-express, npm-package). Copy and customize a new type under ci/ instead.
• Avoid heavy setup in release.sh — Module releases run sequentially in a single container; installing extra packages or changing the environment can slow or break the job.

Usage

When a polyci branch is merged into main branch the latest commit is often a polyci release commit. As a result the merge itself is ignored by polyci and the main branch is not published and deployed. To avoid this, just add an ampty commit after merge before you push to the repository.