CI/CD Repository Structure
Essential knowledgeCore knowledge to understand Fluent Commerce
Changed on:
15 Nov 2026
Overview
[Warning: empty required content area]Key points
[Warning: empty required content area]A single repository per implementation works well for most partners: rules, workflows, settings and pipeline scripts change together and are released together. Split out a separate repository only for code with its own release cadence, for example a Mystique component library shared across clients.
Guidelines
- Keep environment-specific values out of
`modules/`. A module should install identically into any account. Put retailer IDs, endpoints and environment-specific setting values in`cicd/configs/`or in pipeline variables. - Keep credentials out of the repository entirely. Secrets go in pipeline (deployment) variables, never in committed files. See The Fluent CLI.
- Keep scripts vendor-neutral. Scripts take values as arguments or generic environment variables (
`-v <version>`,`FLUENT_PROFILE`) and never read`BITBUCKET_*`variables directly. The pipeline file maps CI variables onto script inputs, so the same scripts run locally and in any CI system. - Gitignore build output.
`modules/*/dist/`,`target/`and`logs/`are produced by the build and must never be committed.
Common Pitfalls
Failure modes seen on real projects, with the guard against each.| Symptom | Cause | Guard |
| Deploy is green but rules did not change | Rules JAR version differs from `module.json`, so the CLI skipped the upload | Have `build-module.sh` fail on a version mismatch (Modules) |
| Deploy is green but a workflow did not update | CLI logged a validation or permission error and exited 0 | Wrap every CLI call with `fluent-cli.sh` (CLI) |
| Opaque 401 partway through a deploy | Step ran without `deployment:`, so the credentials were empty or literal `$NAME` text | Check all variables before calling the CLI (profile.sh) |
Error log shows `{ errors: [Array] }` | Default `util.inspect` depth | Preload `node-deep-inspect.cjs` |
| An old commit no longer builds the same way | Floating Node or CLI version | Pin exact versions in `prepare.sh` |
`mvn test` fails on a clean checkout before any test runs | Reactor modules unpack sibling JARs that only `package` produces | Build with `mvn package` |
| A hotfix disappears on the next release | Fix was made in the environment, or only on the release branch | Detect drift; fix in `dev` first, then cherry-pick |
| Two merged PRs break dev together | Each PR was tested against an old `dev` | Use a merge queue |
| Pipeline variables leak into logs | `set -x`, or echoing a command line that includes a password | Never trace credential-bearing steps; report variable names, not values |
| Deploy installs into the wrong retailer | Retailer list derived from files left in the checkout by another run | Read retailers from one variable (`FLUENT_RETAILERS`) only, with no fallback |
| CLI upgrade makes the error wrapper miss failures | Log message wording changed | Re-check `FAIL_PATTERNS` on every CLI upgrade |