Atmos Policy
Use this skill for the experimental policy engine and reusable library, not for general validation
or ordinary lifecycle-hook configuration. Use atmos-hooks for non-policy hook definitions and
atmos-validation for existing JSON Schema/OPA settings.validation behavior.
Establish capabilities before authoring
Check the installed Atmos version/help and the matching source/docs. Do not infer a command exists
from the PRD: atmos policy check/test/explain is proposed, not implemented in this branch.
The current opt-in is policy.d/ at the project root that atmos.yaml discovery selects (the working directory, then the Git root, then the nearest ancestor with atmos.yaml), overridden by ATMOS_POLICY_DIR, containing strict atmos/v1
kind: Policy documents. Inline CEL and restricted Starlark run. A Starlark predicate is a
function body over detached, read-only JSON data that must return a strict boolean; it has no
automation host, module loader, filesystem, network, or logging API. Rego is not available
through this loader. Existing Rego validation is separate and remains supported. Do not migrate legacy configuration to proposed policy:
attachments yet.
Use central match selectors for instance attachments: literal labels (all), tags (any by default,
tag_mode: all supported), exact component names, stacks, and component types. These use resolved
metadata from existing inheritance, not inline policy inheritance. Protect the governing directory.
Distinguish input kind, component type, and CI provider:
terraform.plan: native JSON extracted privately from a saved binary plan. Evaluated after
successful plan, including no-change plans, and again before applying the evaluated private copy.
Implicit apply/deploy and direct destroy are rejected when plan policies are enabled.
operation: lifecycle event, component type/name, stack, command, status, exit code, dry-run.
Current integration uses existing Terraform, Helmfile, Helm, and Kubernetes hooks. Do not claim
enforcement for Packer, Ansible, containers, emulators, or custom components yet.
plugin (on: plugin): native plugin registries, packages, and local builds (origin, path, profiles, operation)
checked before install, activation, test, publish, and sign. See atmos-plugins for inputs and recipes.
- GitHub Actions context:
ci.provider == 'github-actions', ci.schema == 'github-actions/v1'.
Metadata retains allowlisted environment variable names under ci.metadata.data; native event
fields remain under ci.event.data. No tokens or arbitrary environment variables are copied.
Events are triggering evidence, not current reviews. Missing required data blocks.
atmos.affected: deny rules run in shared affected analysis before output filtering/scheduling.
Inputs include files, instances, component/stack groups, and structured before/after fields.
Collection requires clean worktrees; static inventories use the active, protected discovery
configuration on both revisions. This is not independent historical discovery or a transitive
execution graph. Missing imports and unsupported inventory types block. Inspect before/after
explicitly; affected rules do not accept single-instance match or dispatch lifecycle hooks.
git.change, function/source, and approval input types have core contracts or design examples,
not complete CLI collectors/enforcement. Affected is explicit; ordinary lifecycle and saved-plan
rules do not depend on --affected.
Author and test
- Start with
policy-library/<name>/: each entry has a README.md, one policy.yaml, and
tests/cases.json. Browse /policies/library in the matching-version documentation.
examples/policies/{terraform,github,lifecycle} are demonstration bundles, not the library.
Copy only selected manifests into a protected, flat ATMOS_POLICY_DIR; loading is not recursive.
- Choose a supported input and effect. A true CEL predicate selects its effect; a false predicate
is not applicable, not denial. Use
action: deny for a violation predicate, not a safety
predicate. action: hooks is supported on operation inputs.
- Keep predicates pure. Available roots are
input, params, ci, and request. Supply
parameters with with. No network, shell, filesystem, clock, or automation host is exposed.
Include metadata.description with the document's plain-English purpose. It is optional
literal text, separate from the CEL rule and denial reason; catalog entries require it.
- Treat missing, null, and unknown separately. Read Terraform
after_unknown alongside after.
Deletion includes replacement action lists. Decide whether a removal is forbidden or allowed
remediation. Do not print plan JSON or sensitive values to explain a violation.
- Add colocated
tests/cases.json fixtures for each catalog entry: matching and non-matching
inputs, threshold boundaries, null/missing/unknown data, relevant input kinds, and exact hook
requirements. TestPolicyCatalog loads the actual manifests and checks combined identities.
Demonstration bundles retain table-driven cases in pkg/policy/library_test.go.
- Run targeted tests, not production applies or callbacks:
go test ./pkg/policy -run TestPolicyCatalog -v
go test ./pkg/policy -run TestSampleLibrary -v
go test ./pkg/hooks -run 'TestPolicyHooksLifecycle|TestPolicyHookFailuresBlock'
go test ./pkg/ci/... -run TestPolicySnapshot
Tests prove only the layers they execute. A supplied-data predicate test does not prove CI
collection, approvals, an artifact binding, or component command admission.
Policy-selected hooks
Place hook definitions in governing spec.hooks, not workspace hooks:. Reference them from
an operation rule's hooks list with ref, event, required, and require_success. Local
references resolve to metadata.name/ref. The predicate must select the same lifecycle event
as the hook requirement. Selection happens now, not as scheduling for a later event.
Use existing hook kinds and steps. Keep conditions in the policy: this slice rejects hook-level
events/when and nested skip/background controls, and does not render hook templates or YAML
functions. Use protected executable dependencies; optional spec.tools pins cannot be overridden
by component dependencies. Tool configs and runtime credentials still need protection.
Set both booleans for a mandatory successful check. required prevents --skip-hooks bypass;
require_success forces failure propagation regardless of a hook's weaker on_failure setting.
Dry-run reports selections without executing. A denial is never canceled by a successful hook.
After-apply failures do not roll back completed infrastructure. Avoid callbacks without an
idempotency strategy; there is no durable replay ledger or exactly-once guarantee.
CI and trust boundaries
Reading supplied Actions events requires no API permission. Repository checkout needs
contents: read. Native CI status reporting separately needs statuses: write. Do not recommend
write-all, a PAT, or a GitHub App just to enable OSS policy input. PR reads, current reviews,
check/run facts, review requests, and approval verification are not implemented by this collector.
Live organization-team membership is not a GITHUB_TOKEN workflow permission.
Protect the workflow, governing revision/directory, environment, CODEOWNERS, and executables.
The comparison base is not necessarily the governing revision. Never claim an editable checkout
is tamper-proof. Do not suggest privileged execution of fork code under pull_request_target.
Keep local/current-job evaluation in OSS. Cross-component/job outcome aggregation, durable
coordination, organization identity enrichment, and webhook orchestration belong to Atmos Pro.
Keep unimplemented designs in docs/prd/policies.md, not website docs or runnable catalog entries.
The library governs Atmos operations and consumed artifacts; do not duplicate Kubernetes admission
rules. Required external validators retain ownership of their resource-security rules.
1---2name: atmos-policy3description: "Use when selecting, authoring, or testing Atmos library policies, CEL saved-plan guardrails, policy-selected hooks, or provider-native policy inputs. For existing settings.validation, JSON Schema, and OPA validation commands, use atmos-validation."4metadata:5 source: https://skillmd.com/skills/cloudposse/atmos-policy6---78# Atmos Policy910Use this skill for the experimental policy engine and reusable library, not for general validation11or ordinary lifecycle-hook configuration. Use `atmos-hooks` for non-policy hook definitions and12`atmos-validation` for existing JSON Schema/OPA `settings.validation` behavior.1314## Establish capabilities before authoring1516Check the installed Atmos version/help and the matching source/docs. Do not infer a command exists17from the PRD: `atmos policy check/test/explain` is proposed, not implemented in this branch.1819The current opt-in is `policy.d/` at the project root that `atmos.yaml` discovery selects (the working directory, then the Git root, then the nearest ancestor with `atmos.yaml`), overridden by `ATMOS_POLICY_DIR`, containing strict `atmos/v1`20`kind: Policy` documents. Inline CEL and restricted Starlark run. A Starlark predicate is a21function body over detached, read-only JSON data that must return a strict boolean; it has no22automation host, module loader, filesystem, network, or logging API. Rego is not available23through this loader. Existing Rego validation is separate and remains supported. Do not migrate legacy configuration to proposed `policy:`24attachments yet.2526Use central `match` selectors for instance attachments: literal labels (all), tags (any by default,27`tag_mode: all` supported), exact component names, stacks, and component types. These use resolved28metadata from existing inheritance, not inline policy inheritance. Protect the governing directory.2930Distinguish input kind, component type, and CI provider:3132- `terraform.plan`: native JSON extracted privately from a saved binary plan. Evaluated after33 successful plan, including no-change plans, and again before applying the evaluated private copy.34 Implicit apply/deploy and direct destroy are rejected when plan policies are enabled.35- `operation`: lifecycle event, component type/name, stack, command, status, exit code, dry-run.36 Current integration uses existing Terraform, Helmfile, Helm, and Kubernetes hooks. Do not claim37 enforcement for Packer, Ansible, containers, emulators, or custom components yet.38- `plugin` (`on: plugin`): native plugin registries, packages, and local builds (`origin`, `path`, `profiles`, `operation`)39 checked before install, activation, test, publish, and sign. See `atmos-plugins` for inputs and recipes.40- GitHub Actions context: `ci.provider == 'github-actions'`, `ci.schema == 'github-actions/v1'`.41 Metadata retains allowlisted environment variable names under `ci.metadata.data`; native event42 fields remain under `ci.event.data`. No tokens or arbitrary environment variables are copied.43 Events are triggering evidence, not current reviews. Missing required data blocks.44- `atmos.affected`: deny rules run in shared affected analysis before output filtering/scheduling.45 Inputs include files, instances, component/stack groups, and structured before/after fields.46 Collection requires clean worktrees; static inventories use the active, protected discovery47 configuration on both revisions. This is not independent historical discovery or a transitive48 execution graph. Missing imports and unsupported inventory types block. Inspect before/after49 explicitly; affected rules do not accept single-instance `match` or dispatch lifecycle hooks.50- `git.change`, function/source, and approval input types have core contracts or design examples,51 not complete CLI collectors/enforcement. Affected is explicit; ordinary lifecycle and saved-plan52 rules do not depend on `--affected`.5354## Author and test55561. Start with `policy-library/<name>/`: each entry has a `README.md`, one `policy.yaml`, and57 `tests/cases.json`. Browse `/policies/library` in the matching-version documentation.58 `examples/policies/{terraform,github,lifecycle}` are demonstration bundles, not the library.59 Copy only selected manifests into a protected, flat `ATMOS_POLICY_DIR`; loading is not recursive.602. Choose a supported input and effect. A true CEL predicate selects its effect; a false predicate61 is **not applicable**, not denial. Use `action: deny` for a violation predicate, not a safety62 predicate. `action: hooks` is supported on operation inputs.633. Keep predicates pure. Available roots are `input`, `params`, `ci`, and `request`. Supply64 parameters with `with`. No network, shell, filesystem, clock, or automation host is exposed.65 Include `metadata.description` with the document's plain-English purpose. It is optional66 literal text, separate from the CEL `rule` and denial `reason`; catalog entries require it.674. Treat missing, null, and unknown separately. Read Terraform `after_unknown` alongside `after`.68 Deletion includes replacement action lists. Decide whether a removal is forbidden or allowed69 remediation. Do not print plan JSON or sensitive values to explain a violation.705. Add colocated `tests/cases.json` fixtures for each catalog entry: matching and non-matching71 inputs, threshold boundaries, null/missing/unknown data, relevant input kinds, and exact hook72 requirements. `TestPolicyCatalog` loads the actual manifests and checks combined identities.73 Demonstration bundles retain table-driven cases in `pkg/policy/library_test.go`.746. Run targeted tests, not production applies or callbacks:7576```shell77go test ./pkg/policy -run TestPolicyCatalog -v78go test ./pkg/policy -run TestSampleLibrary -v79go test ./pkg/hooks -run 'TestPolicyHooksLifecycle|TestPolicyHookFailuresBlock'80go test ./pkg/ci/... -run TestPolicySnapshot81```8283Tests prove only the layers they execute. A supplied-data predicate test does not prove CI84collection, approvals, an artifact binding, or component command admission.8586## Policy-selected hooks8788Place hook definitions in governing `spec.hooks`, not workspace `hooks:`. Reference them from89an operation rule's `hooks` list with `ref`, `event`, `required`, and `require_success`. Local90references resolve to `metadata.name/ref`. The predicate must select the same lifecycle event91as the hook requirement. Selection happens now, not as scheduling for a later event.9293Use existing hook kinds and steps. Keep conditions in the policy: this slice rejects hook-level94`events`/`when` and nested skip/background controls, and does not render hook templates or YAML95functions. Use protected executable dependencies; optional `spec.tools` pins cannot be overridden96by component dependencies. Tool configs and runtime credentials still need protection.9798Set both booleans for a mandatory successful check. `required` prevents `--skip-hooks` bypass;99`require_success` forces failure propagation regardless of a hook's weaker `on_failure` setting.100Dry-run reports selections without executing. A denial is never canceled by a successful hook.101After-apply failures do not roll back completed infrastructure. Avoid callbacks without an102idempotency strategy; there is no durable replay ledger or exactly-once guarantee.103104## CI and trust boundaries105106Reading supplied Actions events requires no API permission. Repository checkout needs107`contents: read`. Native CI status reporting separately needs `statuses: write`. Do not recommend108`write-all`, a PAT, or a GitHub App just to enable OSS policy input. PR reads, current reviews,109check/run facts, review requests, and approval verification are not implemented by this collector.110Live organization-team membership is not a `GITHUB_TOKEN` workflow permission.111112Protect the workflow, governing revision/directory, environment, CODEOWNERS, and executables.113The comparison base is not necessarily the governing revision. Never claim an editable checkout114is tamper-proof. Do not suggest privileged execution of fork code under `pull_request_target`.115116Keep local/current-job evaluation in OSS. Cross-component/job outcome aggregation, durable117coordination, organization identity enrichment, and webhook orchestration belong to Atmos Pro.118Keep unimplemented designs in `docs/prd/policies.md`, not website docs or runnable catalog entries.119The library governs Atmos operations and consumed artifacts; do not duplicate Kubernetes admission120rules. Required external validators retain ownership of their resource-security rules.