enablement-build-template-generate
v1.8.3
Published
Generates build yaml for mono repos
Readme
enablement-build-template-generate
Generates pipeline YAML files for monorepos by expanding a job template once per package and stitching the results into a document template. Designed for Azure DevOps but works with any text-based pipeline format.
Usage
npx enablement-build-template-generate@latest [flags]How it works
- Select platform — Uses Azure DevOps (
.cicd/) by default. Pass--platform githubto use GitHub (.github/). - Read config —
{configDir}/templates/templated.jsonis the source of truth. Ifmanifest.jsonstill has atemplatedsection (from older tooling), it's read once, merged intotemplated.json, and removed frommanifest.json. Atemplated.jsonin the legacy{ rootPath, template }shape is converted to the current format (packages discovered by globbingrootPath). - Detect new packages — Any package not yet assigned a template (scanned via
--children/auto-detected workspace roots) is classified by type (node/python/dotnet/docker) and assigned a template, reusing the convention of other packages in the same folder or of the same type where possible. - Persist —
templated.json(andmanifest.json, if it needed migrating) is written back, only when something actually changed. - Expand job templates — For each package, reads its job snippet template and fills in placeholders (
folderName/packageFolder/metadatacome fromtemplated.json's owncicdsection). Packages are ordered so that, permanifest.json'sdependenciesgraph (when present), a package's local dependencies are generated before it, as much as possible. - Stitch — Joins all expanded job snippets and substitutes them into the document template at the named placeholder.
- Write output — Writes the final file one level above the template directory (
.github/templates/→.github/or.cicd/templates/→.cicd/), wrapped inDO NOT EDITbanners.
CLI flags
| Flag | Default | Description |
|---|---|---|
| --platform <name> | ado | Select the platform: ado (Azure DevOps) or github (GitHub Actions). |
| --children <dirs> | auto-detect | Comma- or space-separated list of top-level directories to scan when detecting new (not-yet-configured) packages. When omitted, directories are read from pnpm-workspace.yaml or package.json workspaces automatically. |
| --exclude <list> | — | Comma- or space-separated list of names to skip: package folder names during generation, and top-level directories (from --children or auto-detection) during new-package scanning. |
| --debug | off | Print verbose output. |
Config source
templated.json (current format)
{configDir}/templates/templated.json is the source of truth for template routing. Each key under templated is the output filename; each value maps a placeholder variable name to a per-package template mapping. cicd carries the per-package metadata generation needs.
{
"version": 2,
"templated": {
"build.yml": {
"PACKAGES": {
"my-scope/component-a": "build_node_component.yml",
"my-scope/component-b": ["build_node_component.yml", "build_scan_node.yml"],
"my-scope/python-lib": ["build_python_package.yml", "build_scan.yml"]
}
}
},
"cicd": {
"my-scope/component-a": { "folderName": "component-a", "packageFolder": "packages" }
}
}Each package name maps to a single template filename or an array of template filenames (all expanded in order for that package). Template lookup tries the active platform templates directory first (.cicd/templates/ or .github/templates/) and then falls back to the other platform directory if a file is missing.
Package metadata (folderName, packageFolder, metadata) is read from templated.json's own cicd map and used to fill template placeholders.
A templated.json in the legacy { rootPath, template } shape (no top-level templated/version key) is converted to the current format automatically — packages are discovered by globbing rootPath for package.json/version.json/pyproject.toml, and the result is written back.
manifest.json (one-time migration source + dependency graph)
If {configDir}/manifest.json still has a templated section (from older tooling, or enablement-build-manifest before it stopped writing one), it's merged into templated.json and removed from manifest.json — existing assignments in templated.json win over stale ones from manifest.json.
Independently of that migration, when manifest.json exists its dependencies map ({ "<package>": ["<local-dep>", ...] }) is used to order generation: within each placeholder, a package's local dependencies are generated before it, as much as possible (dependencies outside that placeholder's package list, or on a package that also depends back on it, are simply skipped rather than causing an error).
Template placeholders
Document template
The document template (the top-level YAML file) uses {variableName} placeholders that are replaced with the fully expanded set of job snippets:
# build.yml (document template)
stages:
- stage: Build
jobs:
{PACKAGES}Job template
Each job snippet template is expanded once per package. The following placeholders are available:
| Placeholder | Value |
|---|---|
| {name} | Package folder name (from cicd[pkg].folderName, e.g. my-component) |
| {safe} | Folder name with -, _, and . removed — safe for use as a YAML identifier (e.g. mycomponent) |
| {package} | npm package name without scope prefix (e.g. my-component from @scope/my-component) |
| {full} | Full npm package name including scope (e.g. @scope/my-component) |
| {path} | The package folder root (from cicd[pkg].packageFolder, e.g. packages) |
| {other} | Expands to a comma-separated list of paths to every other package in the same variable — useful for pipeline dependency declarations |
| {metadataKey} | Custom placeholders like {owner} or {tier} are replaced from templated.json's cicd[packageName].metadata |
Custom metadata placeholders aren't supported for a package still being discovered via the legacy { rootPath, template } conversion (they remain unchanged in output) — once converted, templated.json's cicd map can carry metadata for any package.
Directory layout
Job template files live in the templates subfolder; document templates and generated output files are one level up.
Azure DevOps:
.cicd/
├── manifest.json ← optional: dependency graph for ordering, one-time templated migration source
├── build.yml ← generated output
└── templates/
├── build.yml ← document template
├── templated.json ← source of truth for templated config
└── build_node_component.yml ← job snippet templateGitHub Actions:
.github/
├── manifest.json ← optional: dependency graph for ordering, one-time templated migration source
├── build.yml ← generated output
└── templates/
├── build.yml ← document template
├── templated.json ← source of truth for templated config
└── build_node_component.yml ← job snippet templateTypical pipeline usage
Run the generator as a pipeline step before the build stage:
- script: npx enablement-build-template-generate@latest
displayName: Generate pipeline YAMLExcluding specific packages:
npx enablement-build-template-generate@latest --exclude legacy-pkg,test-harnessOutput format
Generated files are wrapped in DO NOT EDIT banners. Edit the templates or re-generate via manifest, not the output directly:
#######################################
### DO NOT EDIT - THIS IS GENERATED ###
#######################################
# ... generated content ...
#######################################
### DO NOT EDIT - THIS IS GENERATED ###
#######################################