Where it goes
Contoso keeps procurement-emea-prod in deployments/procurement-emea-prod.yaml. The loader reads every YAML file under the package root, so folders are a convention you can change. Name it in lowercase kebab-case. The name must be unique among the package's Deployment resources.
Limits
A Deployment in a package file changes nothing by itself. It takes effect when you publish the version and apply the deployment.
Fields
The keys under spec. Nested shapes follow DeploymentSpec in the GOL JSON Schema.
| Field | Presence | Shape |
|---|---|---|
environment | Required | kebab |
package | Required | object |
segments | Required | array |
audiences | Required | array |
channels | Optional | array |
rollout | Optional | object |
gates | Optional | gates |
maxAutonomy | Optional | enum: L0, L1, L2, L3, L4 |
disabled | Optional | array |
window | Optional | object |
approvals | Optional | array |
rollback | Optional | object |
capabilities | Optional | array |
Syntax and rules
The examples are fragments. Put them in a package next to the resources they reference. A ... stands for a CEL expression you write yourself.
11.2 Deployment
kind: Deployment
metadata: { name: procurement-emea-prod }
spec:
environment: production
package: { version: 2.4.0 } # exact; channels (stable, beta) resolve to exact at deploy time
segments: ["segment:procurement-emea"]
audiences: ["audience:emea-procurement", "team:legal-contracts"]
capabilities: ["capability:contract-renewal-desk", "capability:supplier-questions"] # what a client may bind to here
channels: [chat, apps, api, mcp, desktop]
rollout:
strategy: staged
stages:
- { audience: "*", kind: shadow, soak: P3D } # answers generated and scored, shown to nobody
- { audience: "team:legal-contracts", soak: P2D, gates: { citationSupport: 0.92 } }
- { audience: "*" }
gates:
{
citationSupport: 0.90,
goldenPass: 0.95,
refusalCorrectness: 0.90,
denialPrecision: 1.0,
injectionBlocked: 1.0,
outputPiiDetections: 0,
minSamples: 30,
}
maxAutonomy: L3 # caps every action for these audiences (9.1.1)
disabled: # kill switch: takes effect without a new version
- {
ref: "procurement.RenewContract",
by: "user:s.officer",
reason: "ERP webhook double-posting, ticket INC-4411",
since: 2026-10-03T09:12:00Z,
}
window: { notBefore: 2026-10-01T06:00:00Z }
approvals: [{ by: "role:security-officer" }, { by: "role:ontology-owner" }]
rollback: { auto: true, triggers: [validation-regression, error-rate, gate-failure] }
Directory bindings (which Entra group is team:legal-contracts) live in the environment, outside the package, so one package deploys to many tenants.
Promotion. A stage advances only when its soak has passed and every gate is met on the scorecard for that stage. Gates merge per metric: for each metric the strictest of the platform default, the Capability's gates, the deployment's gates and the stage's gates applies (a stage that names only citationSupport keeps every other gate). Each metric has a fixed direction (citationSupport, goldenPass, refusalCorrectness, denialPrecision, injectionBlocked are minimums; outputPiiDetections, compensationsRun, firstTokenP95 are maximums). A metric under minSamples eligible observations, or not applicable to the stage, blocks advancement as insufficient evidence rather than passing. The safety floors (falseAllows: 0, unauthorisedDisclosure: 0, injectionBlocked: 1.0) cannot be lowered by any gate block. A shadow stage deploys the version to the policy decision point and the scorer only: nothing lists it in a chat scope, API document or MCP catalogue, and every audit record it produces carries shadow: true. Advancing past a failing quality gate requires a security approver, a reason, a scope and an expiry, and is audited as an override; a safety floor cannot be overridden.
Supersession. When two live deployments overlap for a subject, the newer package.version applies. A rollback marks its deployment revoked, and a revoked deployment never wins the overlap rule, so the prior version is what the subject sees within a minute. A rollback of a version restores the ontology pointer only; it never restores a permission that was revoked in the meantime, and it never undoes a completed migration backfill (12).
Disable. disabled[] is the kill switch for any action, view, function, Capability, source or model reference. It is operational state kept beside the immutable version, with a monotonic disable revision that is an input to every authorisation decision. It takes effect within 10 seconds, without a new version or an approval, and applies to the element in every deployment of the environment unless scope: this-deployment is given, so an overlapping deployment cannot bypass it. On disable: new invocations are refused, queued runs are cancelled, active streams that would use the element end with a notice, pending approvals for it are voided, worker leases for it are not renewed, and cached schemas and client catalogues drop it on their next refresh (at most 60 s). It is audited with by and reason; only an owner of the element, or a security officer for a source or model, can clear it, and the clearance is audited too. lifecycle.expires behaves as a scheduled disable.
Check your package
gluon validate examples/contoso
gluon test examples/contoso
validate reports each problem with a GLN code and its place in the file. test runs the package's Test resources. See the language guide and the diagnostics.
