@intentius/chant-lexicon-gitlab 0.118.1 → 0.120.0

package/dist/codegen/docs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiFH;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC9E"}
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/codegen/docs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyHH;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC9E"}

package/dist/codegen/naming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/codegen/naming.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,cAAc,IAAI,kBAAkB,EAGrC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAsC,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAErF,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AA8BnF;;;GAGG;AACH,qBAAa,cAAe,SAAQ,kBAAkB;IACpD,YAAY,OAAO,EAAE,iBAAiB,EAAE,EAMvC;CACF"}
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/codegen/naming.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,cAAc,IAAI,kBAAkB,EAGrC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAsC,KAAK,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAErF,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AA+BnF;;;GAGG;AACH,qBAAa,cAAe,SAAQ,kBAAkB;IACpD,YAAY,OAAO,EAAE,iBAAiB,EAAE,EAMvC;CACF"}

package/dist/codegen/parse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/codegen/parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,EAEL,kBAAkB,IAAI,sBAAsB,EAI7C,MAAM,sCAAsC,CAAC;AAI9C,YAAY,EAAE,mBAAmB,EAAE,CAAC;AACpC,OAAO,EAAE,sBAAsB,IAAI,kBAAkB,EAAE,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,yEAAyE;IACzE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA+FD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,EAAE,CAoBxE;AAkcD;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D"}
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/codegen/parse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,EAEL,kBAAkB,IAAI,sBAAsB,EAI7C,MAAM,sCAAsC,CAAC;AAI9C,YAAY,EAAE,mBAAmB,EAAE,CAAC;AACpC,OAAO,EAAE,sBAAsB,IAAI,kBAAkB,EAAE,CAAC;AAExD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAC;IACzB,aAAa,EAAE,kBAAkB,EAAE,CAAC;IACpC,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,yEAAyE;IACzE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA2GD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,iBAAiB,EAAE,CAoBxE;AA6dD;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D"}

package/dist/generated/index.d.ts

@@ -1,5 +1,6 @@
 export declare const Default: new (props: Record<string, unknown>, attributes?: Record<string, unknown>) => import("@intentius/chant").Declarable & Record<string, string>;
 export declare const Job: new (props: Record<string, unknown>, attributes?: Record<string, unknown>) => import("@intentius/chant").Declarable & Record<string, string>;
+export declare const Pipeline: new (props: Record<string, unknown>, attributes?: Record<string, unknown>) => import("@intentius/chant").Declarable & Record<string, string>;
 export declare const Workflow: new (props: Record<string, unknown>, attributes?: Record<string, unknown>) => import("@intentius/chant").Declarable & Record<string, string>;
 export declare const AllowFailure: new (props: Record<string, unknown>) => import("@intentius/chant").Declarable & Record<string, unknown>;
 export declare const Artifacts: new (props: Record<string, unknown>) => import("@intentius/chant").Declarable & Record<string, unknown>;

package/dist/generated/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generated/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,8IAAsE,CAAC;AAC3F,eAAO,MAAM,GAAG,8IAAkE,CAAC;AACnF,eAAO,MAAM,QAAQ,8IAAuE,CAAC;AAE7F,eAAO,MAAM,YAAY,yGAAuE,CAAC;AACjG,eAAO,MAAM,SAAS,yGAAoE,CAAC;AAC3F,eAAO,MAAM,UAAU,yGAAqE,CAAC;AAC7F,eAAO,MAAM,KAAK,yGAAgE,CAAC;AACnF,eAAO,MAAM,WAAW,yGAAsE,CAAC;AAC/F,eAAO,MAAM,KAAK,yGAAgE,CAAC;AACnF,eAAO,MAAM,OAAO,yGAAkE,CAAC;AACvF,eAAO,MAAM,OAAO,yGAAkE,CAAC;AACvF,eAAO,MAAM,IAAI,yGAA+D,CAAC;AACjF,eAAO,MAAM,QAAQ,yGAAmE,CAAC;AACzF,eAAO,MAAM,OAAO,yGAAkE,CAAC;AACvF,eAAO,MAAM,KAAK,yGAAgE,CAAC;AACnF,eAAO,MAAM,IAAI,yGAA+D,CAAC;AACjF,eAAO,MAAM,OAAO,yGAAkE,CAAC;AACvF,eAAO,MAAM,OAAO,yGAAkE,CAAC;AACvF,eAAO,MAAM,YAAY,yGAAuE,CAAC;AAGjG,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generated/index.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,OAAO,8IAAsE,CAAC;AAC3F,eAAO,MAAM,GAAG,8IAAkE,CAAC;AACnF,eAAO,MAAM,QAAQ,8IAAuE,CAAC;AAC7F,eAAO,MAAM,QAAQ,8IAAuE,CAAC;AAE7F,eAAO,MAAM,YAAY,yGAAuE,CAAC;AACjG,eAAO,MAAM,SAAS,yGAAoE,CAAC;AAC3F,eAAO,MAAM,UAAU,yGAAqE,CAAC;AAC7F,eAAO,MAAM,KAAK,yGAAgE,CAAC;AACnF,eAAO,MAAM,WAAW,yGAAsE,CAAC;AAC/F,eAAO,MAAM,KAAK,yGAAgE,CAAC;AACnF,eAAO,MAAM,OAAO,yGAAkE,CAAC;AACvF,eAAO,MAAM,OAAO,yGAAkE,CAAC;AACvF,eAAO,MAAM,IAAI,yGAA+D,CAAC;AACjF,eAAO,MAAM,QAAQ,yGAAmE,CAAC;AACzF,eAAO,MAAM,OAAO,yGAAkE,CAAC;AACvF,eAAO,MAAM,KAAK,yGAAgE,CAAC;AACnF,eAAO,MAAM,IAAI,yGAA+D,CAAC;AACjF,eAAO,MAAM,OAAO,yGAAkE,CAAC;AACvF,eAAO,MAAM,OAAO,yGAAkE,CAAC;AACvF,eAAO,MAAM,YAAY,yGAAuE,CAAC;AAGjG,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC"}

package/dist/integrity.json

@@ -1,9 +1,9 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "c1fbb032e4112bba50f38ddd107b2ca78b519d501211549172134e14c6ff84c3",
-    "meta.json": "931fc3246a55645b1493080bbeb160e5d205e42349e8bdca96ca243adb5f0da3",
-    "types/index.d.ts": "5cd2e99f135a929b72bdd822d00d780d39b1cd407ba0cfb3d511c7ac9d667b58",
+    "manifest.json": "b2e850bbb36b4d9288070eaa6c6f240149f2487a1534b498184d9282a1f0982e",
+    "meta.json": "db082fbf90c5941c498b2bee0f106103449c1a4c257716ca2220f0dd490450b2",
+    "types/index.d.ts": "a048a66ebe20da0cb5fc889054cac69044d9bf882e2c56b5c5bf113d1f3ba57c",
     "rules/artifact-no-expiry.ts": "3f3cabf9792cbf8207e53a25f506715466b19ec25e9c3b4d0d77fed6b2eb4542",
     "rules/deprecated-only-except.ts": "2341b95c0aaf3013c375fb404969858e23451e3430f3d1a63b128fcb21b90156",
     "rules/import-source.ts": "b5b2e79ef4c18a21711a380dce60e8bbab840223eda568b18039879d3a0a549f",
@@ -55,5 +55,5 @@
     "skills/chant-gitlab-migrate.md": "4853d04980560b379e5b0f7267dcb0a1e5d5879cb9e9931681ce76b2a5fe69d8",
     "skills/chant-gitlab-patterns.md": "6d9a44e9e8de4c3820be9d65381b0d2ede4cb3626aaaf0011e21838a9fbf556e"
   },
-  "composite": "d8b0f5de08f945bf3f79d1a76f351def325dae22ddf841d36dd3efbebdafa08a"
+  "composite": "c0d291cbf1bda2ce61c417054a931919434b86868d2022cb9d6efc9d5f0175b2"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gitlab",
-  "version": "0.118.1",
+  "version": "0.120.0",
   "chantVersion": ">=0.1.0",
   "namespace": "GitLab",
   "intrinsics": [

package/dist/meta.json

@@ -181,6 +181,20 @@
     "kind": "property",
     "lexicon": "gitlab"
   },
+  "Pipeline": {
+    "resourceType": "GitLab::CI::Pipeline",
+    "kind": "resource",
+    "lexicon": "gitlab",
+    "constraints": {
+      "stages": {
+        "default": [
+          "build",
+          "test",
+          "deploy"
+        ]
+      }
+    }
+  },
   "Release": {
     "resourceType": "GitLab::CI::Release",
     "kind": "property",

package/dist/okf/index.md

@@ -6,6 +6,7 @@ okf_version: '0.2'
 
 * [Default](/types/Default.md) - GitLab::CI::Default
 * [Job](/types/Job.md) - GitLab::CI::Job
+* [Pipeline](/types/Pipeline.md) - GitLab::CI::Pipeline
 * [Workflow](/types/Workflow.md) - GitLab::CI::Workflow
 
 # Rules

package/dist/okf/rules/WGL034.md

@@ -13,3 +13,4 @@ OIDC id_token mintable from a merge-request pipeline
 ## Applies to
 
 - [Job](/types/Job.md)
+- [Pipeline](/types/Pipeline.md)

package/dist/okf/rules/WGL038.md

@@ -13,3 +13,4 @@ Secret-like variable reachable from a merge-request pipeline
 ## Applies to
 
 - [Job](/types/Job.md)
+- [Pipeline](/types/Pipeline.md)

package/dist/okf/rules/WGL046.md

@@ -13,3 +13,4 @@ Cache populated in a merge-request pipeline (poisoning risk)
 ## Applies to
 
 - [Job](/types/Job.md)
+- [Pipeline](/types/Pipeline.md)

package/dist/okf/rules/WGL048.md

@@ -9,3 +9,7 @@ lexicon: gitlab
 docs: https://intentius.io/chant/lexicons/gitlab/rules/
 ---
 Pipeline defines workflow: but no workflow:name
+
+## Applies to
+
+- [Pipeline](/types/Pipeline.md)

package/dist/okf/types/Default.md

@@ -17,7 +17,7 @@ resource_type: GitLab::CI::Default
 - `hooks` (`Record<string, unknown>`, optional)
 - `id_tokens` (`Record<string, { aud: string | string[] }>`, optional)
 - `identity` (`"google_cloud"`, optional)
-- `image` (`Image`, optional)
+- `image` (`Image | string`, optional)
 - `interruptible` (`boolean`, optional)
 - `retry` (`Retry | number`, optional)
 - `services` (`Service[]`, optional)

package/dist/okf/types/Job.md

@@ -15,6 +15,7 @@ resource_type: GitLab::CI::Job
 - `artifacts` (`Artifacts`, optional)
 - `before_script` (`string | string[]`, optional)
 - `cache` (`Cache | Cache[]`, optional)
+- `comment` (`string`, optional): YAML comment lines written above the job's key. Not a GitLab key; each line of the string becomes a `#` line
 - `coverage` (`string`, optional): Must be a regular expression, optionally but recommended to be quoted, and must be surrounded with '/'. Example: '/Code coverage: \d+\.\d+/'
 - `dependencies` (`string[]`, optional): Specify a list of job names from earlier stages from which artifacts should be loaded. By default, all previous artifacts are passed. Use an empty array to skip downloading artifacts.
 - `environment` (`Environment | string`, optional): Used to associate environment metadata with a deploy. Environment can have a name and URL attached to it, and will be displayed under /environments under the project.
@@ -23,11 +24,11 @@ resource_type: GitLab::CI::Job
 - `hooks` (`Record<string, unknown>`, optional)
 - `id_tokens` (`Record<string, { aud: string | string[] }>`, optional)
 - `identity` (`"google_cloud"`, optional)
-- `image` (`Image`, optional)
+- `image` (`Image | string`, optional)
 - `inherit` (`Inherit`, optional)
 - `interruptible` (`boolean`, optional)
 - `manual_confirmation` (`string`, optional)
-- `needs` (`Need[]`, optional): The list of jobs in previous stages whose sole completion is needed to start the current job.
+- `needs` (`(Need | string)[]`, optional): The list of jobs in previous stages whose sole completion is needed to start the current job.
 - `only` (`any`, optional): Job will run *only* when these filtering options match.
 - `pages` (`Record<string, any> | boolean`, optional)
 - `parallel` (`Parallel | number`, optional)

package/dist/okf/types/Pipeline.md

@@ -0,0 +1,23 @@
+---
+type: resource-type
+title: Pipeline
+description: gitlab resource type GitLab::CI::Pipeline
+name: Pipeline
+lexicon: gitlab
+resource_type: GitLab::CI::Pipeline
+---
+`GitLab::CI::Pipeline`, a resource type of the gitlab lexicon.
+
+## Properties
+
+- `comment` (`string`, optional): YAML comment lines written at the top of the file. Not a GitLab key; each line of the string becomes a `#` line
+- `include` (`Include | string | (Include | string)[]`, optional)
+- `stages` (`string[]`, optional)
+- `variables` (`Record<string, unknown>`, optional)
+
+## Governed by
+
+- [WGL034](/rules/WGL034.md): OIDC id_token mintable from a merge-request pipeline
+- [WGL038](/rules/WGL038.md): Secret-like variable reachable from a merge-request pipeline
+- [WGL046](/rules/WGL046.md): Cache populated in a merge-request pipeline (poisoning risk)
+- [WGL048](/rules/WGL048.md): Pipeline defines workflow: but no workflow:name

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AA0E9D;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAmF9B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AA0F9D;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,UA+G9B,CAAC"}

package/dist/types/index.d.ts

@@ -50,7 +50,7 @@ export declare class Default {
     hooks?: Record<string, unknown>;
     id_tokens?: Record<string, { aud: string | string[] }>;
     identity?: "google_cloud";
-    image?: Image;
+    image?: Image | string;
     interruptible?: boolean;
     retry?: Retry | number;
     services?: Service[];
@@ -123,6 +123,8 @@ export declare class Job {
     artifacts?: Artifacts;
     before_script?: string | string[];
     cache?: Cache | Cache[];
+    /** YAML comment lines written above the job's key. Not a GitLab key; each line of the string becomes a `#` line */
+    comment?: string;
     /** Must be a regular expression, optionally but recommended to be quoted, and must be surrounded with '/'. Example: '/Code coverage: \d+\.\d+/' */
     coverage?: string;
     /** Specify a list of job names from earlier stages from which artifacts should be loaded. By default, all previous artifacts are passed. Use an empty array to skip downloading artifacts. */
@@ -136,12 +138,12 @@ export declare class Job {
     hooks?: Record<string, unknown>;
     id_tokens?: Record<string, { aud: string | string[] }>;
     identity?: "google_cloud";
-    image?: Image;
+    image?: Image | string;
     inherit?: Inherit;
     interruptible?: boolean;
     manual_confirmation?: string;
     /** The list of jobs in previous stages whose sole completion is needed to start the current job. */
-    needs?: Need[];
+    needs?: (Need | string)[];
     /** Job will run *only* when these filtering options match. */
     only?: any;
     pages?: Record<string, any> | boolean;
@@ -188,6 +190,16 @@ export declare class Parallel {
   });
 }
 
+export declare class Pipeline {
+  constructor(props: {
+    /** YAML comment lines written at the top of the file. Not a GitLab key; each line of the string becomes a `#` line */
+    comment?: string;
+    include?: Include | string | (Include | string)[];
+    stages?: string[];
+    variables?: Record<string, unknown>;
+  });
+}
+
 export declare class Release {
   constructor(props: {
     /** Specifies the longer description of the Release. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.118.1",
+  "version": "0.120.0",
   "description": "GitLab CI lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -67,8 +67,8 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.118.1",
-    "@intentius/chant-lexicon-github": "^0.118.1",
+    "@intentius/chant": "^0.120.0",
+    "@intentius/chant-lexicon-github": "^0.120.0",
     "typescript": "^5.9.3"
   },
   "peerDependenciesMeta": {

package/src/codegen/docs.ts

@@ -30,12 +30,12 @@ npm install --save-dev @intentius/chant-lexicon-gitlab
 
 {{file:docs-snippets/src/quickstart.ts}}
 
-The lexicon provides **3 resources** (Job, Workflow, Default), **16 property types** (Image, Cache, Artifacts, Rule, Environment, Trigger, Need, Service, and more), the \`CI\` pseudo-parameter object for predefined variables, and the \`reference()\` intrinsic for YAML \`!reference\` tags. It also ships **4 lint rules** + **39 post-synth checks** (including a CI/CD supply-chain security pass, WGL029–048) and a [\`chant migrate\`](./migration) source for translating GitHub Actions workflows.
+The lexicon provides **4 resources** (Job, Workflow, Default, Pipeline), **16 property types** (Image, Cache, Artifacts, Rule, Environment, Trigger, Need, Service, and more), the \`CI\` pseudo-parameter object for predefined variables, and the \`reference()\` intrinsic for YAML \`!reference\` tags. It also ships **4 lint rules** + **39 post-synth checks** (including a CI/CD supply-chain security pass, WGL029–048) and a [\`chant migrate\`](./migration) source for translating GitHub Actions workflows.
 `;
 
 const outputFormat = `The GitLab lexicon serializes resources into **\`.gitlab-ci.yml\` YAML**. Keys are
-converted to \`snake_case\` and jobs use kebab-case names. Stages are automatically
-collected from all job definitions.
+converted to \`snake_case\` and jobs use kebab-case names. Stages are collected
+from the job definitions, after any a \`Pipeline\` lists.
 
 ## Building
 
@@ -48,7 +48,8 @@ chant build
 
 The generated file includes:
 
-- \`stages:\` list — automatically collected from all job \`stage\` properties
+- a header comment, \`include:\` and \`variables:\`, if a \`Pipeline\` resource is exported
+- \`stages:\` list: a \`Pipeline\`'s \`stages\` in its order, then every other stage a job's \`stage\` names, in first use
 - \`default:\` section — if a \`Default\` resource is exported
 - \`workflow:\` section — if a \`Workflow\` resource is exported
 - Job definitions with \`snake_case\` keys and \`kebab-case\` job names
@@ -61,6 +62,45 @@ The generated file includes:
 | \`expire_in: "1 week"\` | \`expire_in: 1 week\` | Property names use spec-native snake_case |
 | \`new Image({ name: "node:20" })\` | \`image: node:20\` | Single-property objects are collapsed |
 
+## Top-level keys and comments
+
+A \`Pipeline\` resource holds the top-level keys that are not a job, \`default\` or \`workflow\`: \`include\`, \`stages\` and \`variables\`. Its \`stages\` can name a stage no declared job uses, such as one an included file's jobs run in, and set the order; a stage a job names that the list leaves out is still added after it, so the file stays valid. \`variables\` holds pipeline-wide variables, which \`Default\` cannot, since GitLab's \`default:\` has none.
+
+\`Pipeline\` and \`Job\` also take a \`comment\`, written as \`#\` lines: the pipeline's at the top of the file, a job's above its key.
+
+\`\`\`typescript
+export const pipeline = new Pipeline({
+  comment: "Protect the writer's variables and scope them to their environment.",
+  include: [{ local: ".gitlab/watch.yml" }],
+  stages: ["review", "apply", "ops"],
+  variables: { GIT_DEPTH: "0" },
+});
+
+export const lint = new Job({ comment: "Blocks the merge.", stage: "review", image: "node:22", script: ["npm run lint"] });
+\`\`\`
+
+\`\`\`yaml
+# Protect the writer's variables and scope them to their environment.
+
+include:
+  - local: .gitlab/watch.yml
+
+stages:
+  - review
+  - apply
+  - ops
+
+variables:
+  GIT_DEPTH: '0'
+
+# Blocks the merge.
+lint:
+  stage: review
+  image: node:22
+  script:
+    - npm run lint
+\`\`\`
+
 ## Validating locally
 
 The output is standard GitLab CI YAML. Validate with the GitLab CI Lint API or locally:

package/src/codegen/naming.ts

@@ -17,6 +17,7 @@ const gitlabNamingConfig: NamingConfig = {
     "GitLab::CI::Job": "Job",
     "GitLab::CI::Default": "Default",
     "GitLab::CI::Workflow": "Workflow",
+    "GitLab::CI::Pipeline": "Pipeline",
     "GitLab::CI::Artifacts": "Artifacts",
     "GitLab::CI::Cache": "Cache",
     "GitLab::CI::Image": "Image",

package/src/codegen/parse.test.ts

@@ -5,19 +5,20 @@ import { loadSchemaFixture } from "../testdata/load-fixtures";
 const fixture = loadSchemaFixture();
 
 describe("parseCISchema", () => {
-  test("returns 19 entities", () => {
+  test("returns 20 entities", () => {
     const results = parseCISchema(fixture);
-    expect(results).toHaveLength(19);
+    expect(results).toHaveLength(20);
   });
 
-  test("returns 3 resource entities", () => {
+  test("returns 4 resource entities", () => {
     const results = parseCISchema(fixture);
     const resources = results.filter((r) => !r.isProperty);
-    expect(resources).toHaveLength(3);
+    expect(resources).toHaveLength(4);
     const names = resources.map((r) => r.resource.typeName);
     expect(names).toContain("GitLab::CI::Job");
     expect(names).toContain("GitLab::CI::Default");
     expect(names).toContain("GitLab::CI::Workflow");
+    expect(names).toContain("GitLab::CI::Pipeline");
   });
 
   test("returns 16 property entities", () => {
@@ -146,8 +147,17 @@ describe("spec conformance — type mappings", () => {
     expect(findProp("Job", "release")?.tsType).toBe("Release");
   });
 
-  test("Job.needs → Need[]", () => {
-    expect(findProp("Job", "needs")?.tsType).toBe("Need[]");
+  test("Job.needs → (Need | string)[] and Job.image → Image | string (#3669)", () => {
+    expect(findProp("Job", "needs")?.tsType).toBe("(Need | string)[]");
+    expect(findProp("Job", "image")?.tsType).toBe("Image | string");
+  });
+
+  test("Pipeline holds the top-level include, stages and variables, and a comment (#3669)", () => {
+    expect(findProp("Pipeline", "include")?.tsType).toBe("Include | string | (Include | string)[]");
+    expect(findProp("Pipeline", "stages")?.tsType).toBe("string[]");
+    expect(findProp("Pipeline", "variables")).toBeDefined();
+    expect(findProp("Pipeline", "comment")?.tsType).toBe("string");
+    expect(findProp("Job", "comment")?.tsType).toBe("string");
   });
 
   test("Job.inherit → Inherit", () => {

package/src/codegen/parse.ts

@@ -104,6 +104,8 @@ const RESOURCE_ENTITIES: Array<{
   /** Schema path — "root" for root object, or "#/definitions/<name>" */
   source: string;
   description?: string;
+  /** Only these properties of the source (the root object holds every top-level key). */
+  pick?: string[];
 }> = [
   {
     typeName: "GitLab::CI::Job",
@@ -120,6 +122,16 @@ const RESOURCE_ENTITIES: Array<{
     source: "root:workflow",
     description: "Pipeline-level workflow configuration",
   },
+  {
+    // The top-level keys that are neither a job, `default` nor `workflow`
+    // (#3669). The serializer writes them first, so an explicit `stages`
+    // list can name a stage no declared job uses (one an included file's
+    // jobs run in) and set the order.
+    typeName: "GitLab::CI::Pipeline",
+    source: "root",
+    description: "Top-level pipeline keys: include, stages and variables",
+    pick: ["include", "stages", "variables"],
+  },
 ];
 
 /**
@@ -181,14 +193,19 @@ export function parseCISchema(data: string | Buffer): GitLabParseResult[] {
  */
 function extractResourceEntity(
   schema: CISchema,
-  entity: { typeName: string; source: string; description?: string },
+  entity: { typeName: string; source: string; description?: string; pick?: string[] },
 ): GitLabParseResult | null {
   const def = resolveSource(schema, entity.source);
   if (!def) return null;
 
   // Find the object variant if it's a oneOf/anyOf
-  const objectDef = findObjectVariant(def, schema);
-  if (!objectDef?.properties) return null;
+  const found = findObjectVariant(def, schema);
+  if (!found?.properties) return null;
+  const pick = entity.pick;
+  const objectDef: CISchemaDefinition = pick
+    ? { ...found, properties: Object.fromEntries(Object.entries(found.properties).filter(([k]) => pick.includes(k))), required: undefined }
+    : found;
+  if (!objectDef.properties) return null;
 
   const requiredSet = new Set<string>(objectDef.required ?? []);
   const properties = parseProperties(objectDef.properties, requiredSet, schema);
@@ -203,6 +220,8 @@ function extractResourceEntity(
       }
     }
   }
+  const comment = COMMENT_PROPERTIES[entity.typeName];
+  if (comment) properties.push({ name: "comment", tsType: "string", required: false, description: comment, constraints: {} });
 
   // Extract nested property types from definition properties
   const { propertyTypes, enums } = extractNestedTypes(objectDef, shortName, schema);
@@ -270,12 +289,23 @@ function extractPropertyEntity(
   };
 }
 
+/**
+ * Resources that carry a `comment`: not a GitLab key, but `#` lines the
+ * serializer writes above the entry (#3669, as #3667 for github).
+ */
+const COMMENT_PROPERTIES: Record<string, string> = {
+  "GitLab::CI::Pipeline": "YAML comment lines written at the top of the file. Not a GitLab key; each line of the string becomes a `#` line",
+  "GitLab::CI::Job": "YAML comment lines written above the job's key. Not a GitLab key; each line of the string becomes a `#` line",
+};
+
 // ── Helpers ────────────────────────────────────────────────────────
 
 /**
  * Resolve a source path to a schema definition.
  */
 function resolveSource(schema: CISchema, source: string): CISchemaDefinition | null {
+  if (source === "root") return { properties: schema.properties } as CISchemaDefinition;
+
   if (source.startsWith("#/definitions/")) {
     // Array item extraction: "#/definitions/foo:item" → foo.items object variant
     if (source.includes(":item")) {
@@ -541,9 +571,18 @@ const RESOURCE_PROPERTY_OVERRIDES: Record<string, Record<string, string>> = {
     environment: "Environment | string",
     trigger: "Trigger | string",
     release: "Release",
-    needs: "Need[]",
+    // GitLab takes the plain forms too: `image: node:22`, `needs: [build]`.
+    image: "Image | string",
+    needs: "(Need | string)[]",
     inherit: "Inherit",
   },
+  "GitLab::CI::Default": {
+    image: "Image | string",
+  },
+  "GitLab::CI::Pipeline": {
+    include: "Include | string | (Include | string)[]",
+    stages: "string[]",
+  },
   "GitLab::CI::Workflow": {
     rules: "WorkflowRule[]",
   },

package/src/codegen/snapshot.test.ts

@@ -10,7 +10,7 @@ describe("generated lexicon-gitlab.json", () => {
   test.skipIf(!hasGenerated)("is valid JSON with expected entries", () => {
     const content = readFileSync(join(generatedDir, "lexicon-gitlab.json"), "utf-8");
     const registry = JSON.parse(content);
-    expect(Object.keys(registry)).toHaveLength(19);
+    expect(Object.keys(registry)).toHaveLength(20);
   });
 
   test.skipIf(!hasGenerated)("contains all resource entities", () => {

package/src/components/generate-op-pipeline.test.ts

@@ -454,7 +454,7 @@ describe("generateGitlabOpPipeline: a deployment environment (#2257)", () => {
    */
   const YAML_BEFORE_2257 =
     [
-      '# chant Ops (#927, #2084, #2293) — one job per Op under stage "ops", each',
+      '# chant Ops — one job per Op under stage "ops", each',
       "# selected by its own rules:. A merge_request_event or push job needs no",
       "# setup; its rule fires on the event itself.",
       "#",

package/src/components/generate-op-pipeline.ts

@@ -505,7 +505,7 @@ export function generateGitlabOpPipeline(
   }
 
   const headerLines = [
-    `# chant Ops (#927, #2084, #2293) — one job per Op under stage "${stage}", each`,
+    `# chant Ops — one job per Op under stage "${stage}", each`,
     "# selected by its own rules:. A merge_request_event or push job needs no",
     "# setup; its rule fires on the event itself.",
   ];

package/src/components/generate-op-waves-pipeline.ts

@@ -95,7 +95,7 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
     );
   }
   const header = [
-    `# chant Op waves "${spec.name}" (#3679): one stage per wave, each needing the one before.`,
+    `# chant Op waves "${spec.name}": one stage per wave, each needing the one before.`,
     "# A wave that waits at its gate exits 3 and stops the waves after it; approve the",
     "# digest it prints, then retry the job.",
     ...(spec.resume

package/src/coverage.test.ts

@@ -12,8 +12,8 @@ describe("coverage analysis", () => {
     const { computeCoverage } = await import("./coverage");
     const lexiconJSON = readFileSync(lexiconPath, "utf-8");
     const report = computeCoverage(lexiconJSON);
-    expect(report.resourceCount).toBe(3); // Job, Default, Workflow
-    expect(report.resources).toHaveLength(3);
+    expect(report.resourceCount).toBe(4); // Job, Default, Workflow, Pipeline
+    expect(report.resources).toHaveLength(4);
   });
 
   test.skipIf(!hasGenerated)("reports resource names correctly", async () => {
@@ -42,6 +42,6 @@ describe("coverage analysis", () => {
     const report = computeCoverage(lexiconJSON);
     const summary = formatSummary(report);
     expect(summary).toContain("Coverage Report");
-    expect(summary).toContain("3 resources");
+    expect(summary).toContain("4 resources");
   });
 });

package/src/generated/index.d.ts

@@ -50,7 +50,7 @@ export declare class Default {
     hooks?: Record<string, unknown>;
     id_tokens?: Record<string, { aud: string | string[] }>;
     identity?: "google_cloud";
-    image?: Image;
+    image?: Image | string;
     interruptible?: boolean;
     retry?: Retry | number;
     services?: Service[];
@@ -123,6 +123,8 @@ export declare class Job {
     artifacts?: Artifacts;
     before_script?: string | string[];
     cache?: Cache | Cache[];
+    /** YAML comment lines written above the job's key. Not a GitLab key; each line of the string becomes a `#` line */
+    comment?: string;
     /** Must be a regular expression, optionally but recommended to be quoted, and must be surrounded with '/'. Example: '/Code coverage: \d+\.\d+/' */
     coverage?: string;
     /** Specify a list of job names from earlier stages from which artifacts should be loaded. By default, all previous artifacts are passed. Use an empty array to skip downloading artifacts. */
@@ -136,12 +138,12 @@ export declare class Job {
     hooks?: Record<string, unknown>;
     id_tokens?: Record<string, { aud: string | string[] }>;
     identity?: "google_cloud";
-    image?: Image;
+    image?: Image | string;
     inherit?: Inherit;
     interruptible?: boolean;
     manual_confirmation?: string;
     /** The list of jobs in previous stages whose sole completion is needed to start the current job. */
-    needs?: Need[];
+    needs?: (Need | string)[];
     /** Job will run *only* when these filtering options match. */
     only?: any;
     pages?: Record<string, any> | boolean;
@@ -188,6 +190,16 @@ export declare class Parallel {
   });
 }
 
+export declare class Pipeline {
+  constructor(props: {
+    /** YAML comment lines written at the top of the file. Not a GitLab key; each line of the string becomes a `#` line */
+    comment?: string;
+    include?: Include | string | (Include | string)[];
+    stages?: string[];
+    variables?: Record<string, unknown>;
+  });
+}
+
 export declare class Release {
   constructor(props: {
     /** Specifies the longer description of the Release. */

package/src/generated/index.ts

@@ -3,6 +3,7 @@ import { createResource, createProperty } from "./runtime";
 
 export const Default = /* @__PURE__ */ createResource("GitLab::CI::Default", "gitlab", {});
 export const Job = /* @__PURE__ */ createResource("GitLab::CI::Job", "gitlab", {});
+export const Pipeline = /* @__PURE__ */ createResource("GitLab::CI::Pipeline", "gitlab", {});
 export const Workflow = /* @__PURE__ */ createResource("GitLab::CI::Workflow", "gitlab", {});
 
 export const AllowFailure = /* @__PURE__ */ createProperty("GitLab::CI::AllowFailure", "gitlab");

package/src/generated/lexicon-gitlab.json

@@ -181,6 +181,20 @@
     "kind": "property",
     "lexicon": "gitlab"
   },
+  "Pipeline": {
+    "resourceType": "GitLab::CI::Pipeline",
+    "kind": "resource",
+    "lexicon": "gitlab",
+    "constraints": {
+      "stages": {
+        "default": [
+          "build",
+          "test",
+          "deploy"
+        ]
+      }
+    }
+  },
   "Release": {
     "resourceType": "GitLab::CI::Release",
     "kind": "property",

package/src/plugin.test.ts

@@ -292,7 +292,7 @@ jobs:
     const result = await catalog.handler();
     const parsed = JSON.parse(result);
     expect(Array.isArray(parsed)).toBe(true);
-    expect(parsed.length).toBe(19);
+    expect(parsed.length).toBe(20);
     const job = parsed.find((e: { className: string }) => e.className === "Job");
     expect(job).toBeDefined();
     expect(job.kind).toBe("resource");

package/src/serializer.test.ts

@@ -447,3 +447,73 @@ describe("nested objects and arrays", () => {
     expect(output).toContain("parallel: 5");
   });
 });
+
+describe("Pipeline: top-level include, stages and variables, and comments (#3669)", () => {
+  const Pipeline = createResource("GitLab::CI::Pipeline", "gitlab", {});
+  const Job = createResource("GitLab::CI::Job", "gitlab", {});
+  const Include = createProperty("GitLab::CI::Include", "gitlab");
+  const Image = createProperty("GitLab::CI::Image", "gitlab");
+
+  test("renders include, an explicit stage list naming a stage no job uses, variables and comments", () => {
+    const entities = new Map<string, Declarable>([
+      ["pipeline", new Pipeline({
+        comment: "Protect the writer variables.\n\nScope each to its environment.",
+        include: [new Include({ local: ".gitlab/apply.yml" }), { local: ".gitlab/watch.yml" }],
+        stages: ["review", "apply", "ops"],
+        variables: { GIT_DEPTH: "0" },
+      }) as unknown as Declarable],
+      ["lint", new Job({ comment: "Blocks the merge.", stage: "review", image: "node:22", script: ["npm run lint"] }) as unknown as Declarable],
+      ["apply", new Job({ stage: "apply", image: new Image({ name: "node:22" }), needs: ["lint"], script: ["npm run apply"] }) as unknown as Declarable],
+    ]);
+
+    expect(gitlabSerializer.serialize(entities)).toBe(`# Protect the writer variables.
+#
+# Scope each to its environment.
+
+include:
+  - local: .gitlab/apply.yml
+  - local: .gitlab/watch.yml
+
+stages:
+  - review
+  - apply
+  - ops
+
+variables:
+  GIT_DEPTH: '0'
+
+# Blocks the merge.
+lint:
+  stage: review
+  image: node:22
+  script:
+    - npm run lint
+
+apply:
+  stage: apply
+  image:
+    name: node:22
+  needs:
+    - lint
+  script:
+    - npm run apply
+`);
+  });
+
+  test("a stage a job names but the list leaves out is appended, so the file stays valid", () => {
+    const entities = new Map<string, Declarable>([
+      ["pipeline", new Pipeline({ stages: ["apply", "review"] }) as unknown as Declarable],
+      ["lint", new Job({ stage: "lint", script: ["x"] }) as unknown as Declarable],
+      ["plan", new Job({ stage: "review", script: ["x"] }) as unknown as Declarable],
+    ]);
+    expect(gitlabSerializer.serialize(entities)).toContain("stages:\n  - apply\n  - review\n  - lint\n");
+  });
+
+  test("a single include string renders as a one-item list, and no Pipeline leaves the output as before", () => {
+    const one = new Map<string, Declarable>([["p", new Pipeline({ include: "templates/ci.yml" }) as unknown as Declarable]]);
+    expect(gitlabSerializer.serialize(one)).toBe("include:\n  - templates/ci.yml\n");
+
+    const jobsOnly = new Map<string, Declarable>([["build", new Job({ stage: "build", script: ["make"] }) as unknown as Declarable]]);
+    expect(gitlabSerializer.serialize(jobsOnly)).toBe("stages:\n  - build\n\nbuild:\n  stage: build\n  script:\n    - make\n");
+  });
+});

package/src/serializer.ts

@@ -15,6 +15,22 @@ import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-w
 import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
 import { emitYAMLEntry } from "@intentius/chant/yaml";
 
+/**
+ * `#` lines for a comment, one per line of the string (#3669). Only the file
+ * header and job comments exist, and both sit at column 0.
+ */
+function commentLines(comment: string): string {
+  return comment.split("\n").map((l) => `#${l.trimEnd() ? ` ${l.trimEnd()}` : ""}`).join("\n");
+}
+
+/** An entity's props without `comment`, and the comment if it is a non-empty string. */
+function splitComment(entity: Declarable): { props: Record<string, unknown> | undefined; comment?: string } {
+  const props = isResourceDeclarable(entity) ? (entity.props as Record<string, unknown> | undefined) : undefined;
+  if (!props || !("comment" in props)) return { props };
+  const { comment, ...rest } = props;
+  return { props: rest, comment: typeof comment === "string" && comment !== "" ? comment : undefined };
+}
+
 /**
  * GitLab CI visitor for the generic serializer walker.
  */
@@ -101,6 +117,7 @@ export const gitlabSerializer: Serializer = {
 
     // Separate entities by type
     const jobs: Array<[string, Declarable]> = [];
+    const pipelines: Array<[string, Declarable]> = [];
     const defaults: Array<[string, Declarable]> = [];
     const workflows: Array<[string, Declarable]> = [];
     const others: Array<[string, Declarable]> = [];
@@ -115,13 +132,40 @@ export const gitlabSerializer: Serializer = {
         defaults.push([name, entity]);
       } else if (entityType === "GitLab::CI::Workflow") {
         workflows.push([name, entity]);
+      } else if (entityType === "GitLab::CI::Pipeline") {
+        pipelines.push([name, entity]);
       } else {
         others.push([name, entity]);
       }
     }
 
-    // Emit stages (collect from jobs)
-    const stages = new Set<string>();
+    // The Pipeline entity's top-level keys (#3669). More than one is merged
+    // in declaration order: comments joined, includes concatenated, stages
+    // in first-listed order, later variables overriding earlier ones.
+    const headers: string[] = [];
+    const includes: unknown[] = [];
+    const declaredStages: string[] = [];
+    let variables: Record<string, unknown> | undefined;
+    for (const [, entity] of pipelines) {
+      const { props, comment } = splitComment(entity);
+      if (comment) headers.push(comment);
+      const converted = toYAMLValue(props, entityNames) as Record<string, unknown> | undefined;
+      if (!converted) continue;
+      if (converted.include !== undefined) {
+        includes.push(...(Array.isArray(converted.include) ? converted.include : [converted.include]));
+      }
+      if (Array.isArray(converted.stages)) declaredStages.push(...converted.stages.map(String));
+      if (converted.variables && typeof converted.variables === "object") {
+        variables = { ...variables, ...(converted.variables as Record<string, unknown>) };
+      }
+    }
+    if (headers.length > 0) sections.push(commentLines(headers.join("\n\n")));
+    if (includes.length > 0) sections.push(emitYAMLEntry("include", includes));
+
+    // Stages: a Pipeline's explicit list first, in its order, then any stage
+    // a job names that the list leaves out, in first use. Without a list,
+    // that is the jobs' stages alone.
+    const stages = new Set<string>(declaredStages);
     for (const [, entity] of jobs) {
       const props = isResourceDeclarable(entity) ? (entity.props as Record<string, unknown> | undefined) : undefined;
       if (props?.stage && typeof props.stage === "string") {
@@ -131,6 +175,7 @@ export const gitlabSerializer: Serializer = {
     if (stages.size > 0) {
       sections.push(emitYAMLEntry("stages", [...stages]));
     }
+    if (variables && Object.keys(variables).length > 0) sections.push(emitYAMLEntry("variables", variables));
 
     // Emit defaults
     for (const [, entity] of defaults) {
@@ -156,14 +201,13 @@ export const gitlabSerializer: Serializer = {
 
     // Emit jobs
     for (const [name, entity] of jobs) {
-      const converted = toYAMLValue(
-        (isResourceDeclarable(entity) ? entity.props : undefined),
-        entityNames,
-      ) as Record<string, unknown> | undefined;
+      const { props, comment } = splitComment(entity);
+      const converted = toYAMLValue(props, entityNames) as Record<string, unknown> | undefined;
       if (converted) {
         // Convert job name from camelCase to kebab-case for YAML
         const yamlName = name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-        sections.push(emitYAMLEntry(yamlName, converted));
+        const entry = emitYAMLEntry(yamlName, converted);
+        sections.push(comment ? `${commentLines(comment)}\n${entry}` : entry);
       }
     }