Atmos Is Now a Language for Automation
Atmos is now a language for automation. Introducing the Atmos Automation Language: a Python-like language based on Starlark for writing, composing, and testing your build, test, and deployment processes.
Templating made configuration reusable. Custom commands gave teams their own CLI. The Atmos Automation Language is the next major step: you can program the process itself, with functions, control flow, structured data, and tests, using the capabilities already built into Atmos.
Build containers, ship them, and deploy them through the same scripts locally and in CI. Install pinned tools, assume configured identities, run commands, and parallelize independent work. Use consistent inputs, formatted output, and structured errors to make that automation useful to the whole team. It works for applications as well as infrastructure.
Write your code in a .star file and run it with atmos ./release.star, or
embed it in custom commands, workflow steps, and hooks. The interpreter ships
in the Atmos binary, together with the automation functions and test runner.
Your scripts use the tools, credentials, and configuration you provide for each
environment.
Use the same language inside stack manifests with the
!starlark YAML function. Derive resource tags,
names, and environment-specific settings from each component's configuration,
and return typed values directly to YAML.
For standalone .star apps with their own arguments and help, see the
Atmos interpreter announcement.
Keep your release process in one place
Keep release logic with your project. Put it in functions, pass structured values between them, and test their behavior locally. Your CI pipeline invokes the same process your team uses during development, with its own triggers, credentials, and approvals.
Use custom commands for your team's entry points, workflows to compose the process, and lifecycle hooks for checks tied to component operations. They all run the same language and can load shared functions.
Run scripts inside Atmos
Set type: script and interpreter: starlark on a step inside a custom command,
workflow, or hook. The interpreter is included in Atmos.
Why Starlark?
See why Atmos uses Starlark for the language's syntax, built-in capabilities, and execution model.
How to Use It
Add an Atmos subcommand
Save this configuration as atmos.yaml. It defines a capacity command with a
--replicas flag and a script that calculates total worker capacity:
With Atmos installed, run from the directory containing that file:
atmos capacity --replicas 3
The command prints 3 replicas x 4 workers = 12 workers. The script reads
ctx.flags["replicas"], converts it to an integer, and rejects counts below one.
Run atmos capacity --help for the command's generated help. This example needs
no stacks or external tools.
Guard an operation with a hook
A lifecycle hook runs automatically when Atmos reaches a component event.
The owner-check example reads ctx.component.vars
before a Terraform plan and requires the component to have an owner.
With Atmos and Terraform installed, run these commands from the example's directory:
atmos terraform plan api -s dev
atmos terraform plan api -s unowned
The dev stack passes the check and Terraform reports no changes. The unowned
stack fails with Set an owner before planning api, stopping the plan. The
example module has no providers or resources and needs no cloud credentials.
Share functions between scripts
Move shared code into .star files. Include a script in a YAML step with
script: !include scripts/plan.star, and use load() inside the script to import
functions from other files. Imports resolve relative to the file containing
the load() statement. See files and shared code.
The release-plan example loads a shared function and reads three components with at most two tasks running at once. It prints their configuration without deploying anything:
Derive configuration from the stack that uses it
Define resource tags once and let each environment supply its own stage, region, and owner. Add the rule to a shared component definition:
vars:
resource_tags: !starlark |
return {
"Environment": ctx.vars["stage"],
"Region": ctx.vars["region"],
"Owner": ctx.metadata.get("owner", "platform"),
}
Atmos supplies a read-only context after imports, inheritance, and overrides. An inherited expression reads the consuming component's values: development gets development tags, and production gets production tags. Returned maps, lists, booleans, and numbers retain their types.
Use conditions, comprehensions, and helper functions to express configuration
rules. Atmos resolves computed dependencies when accessed and reports cycles
with the fields involved. Inspect the result with
atmos describe component <component> -s <stack> before deploying.
The !starlark reference covers context fields,
return types, and evaluation scope. Use automation scripts for commands and
steps, and YAML expressions for computing configuration values.
Next steps
Follow the custom command guide, workflow guide, or hook guide to add a script to your project. Use the testing guide to check its behavior and report failures.
