cloudposse/atmos v1.233.0-rc.0

on GitHub

• Generate a 1200×630 PNG fallback and per-page JPEG social cards, wire generation and tests into the website lifecycle, and update Open Graph/Twitter metadata regardless of attribute order.

• Use official Atmos and Atmos CI gradient lockups, bundled Geist fonts, measured text wrapping, a darker background, versioned image URLs, safe section-label lookups, and yielding between renders to release native memory.

• Pin website preview and production builds to setup-go v6.5.0 to use the Node.js 24 action runtime.

why

• Make shared documentation and changelog links recognizable and readable with page-specific titles, descriptions, and consistent Atmos branding.

references

• Validation: 16 social-card tests and all 22 prebuild checks pass, including regressions for metadata parsing, image dimensions, prototype-named routes, alien rendering, and yielding between cards; the production website build generates 2,886 cards successfully with unrelated site warnings.

Summary by CodeRabbit

• New Features
  • Website pages now display branded, page-specific preview images when shared on social platforms, with titles and descriptions reflected in the card where available.
  • A branded default preview image is available for pages without a page-specific card.

• Add reusable, dated behavior gates with inspection through edition diffs and descriptions, plus boundary and error-path tests.
• Update journal invariants and contributor guidance; no production behavior is gated by this prerequisite alone.

why

• Allow an edition pin to preserve a previous code path without introducing another configuration toggle.

references

• Prerequisite for #3378 (the plan-diff exclusions fix for #2088)
• Validation: edition race tests, focused config/command tests, Go build, and lint passed

Summary by CodeRabbit

• New Features
  • Edition pins can select older or newer behavior based on the pin date; unpinned projects use the newer path.
  • Edition comparisons, pin descriptions, and date-range results include behavior transitions alongside configuration changes.
  • Terraform plan diffs and deployment verification support exact resource-type and top-level attribute exclusions, configurable across editions.
  • Current editions display computed-attribute changes that older editions hid; unknown values are rendered as “known after apply.”
• Bug Fixes
  • Invalid edition pins, malformed exclusion entries, and unrecognized behavior keys return errors. Unmatched exclusions generate warnings.
• Documentation
  • Updated edition and plan-diff guidance, including transition dates and exclusion behavior.

• Fork PRs now get the Quality Gate: the CI Timing Summary coordinator (.github/actions/stopwatch) and the quality report (magefiles/qualitygate) resolve a fork run's PR by head owner:branch (plus a SHA search for check_run/status events) when workflow_run.pull_requests and commits/{sha}/pulls are empty. The head SHA is still re-verified against the PR before anything is published.
• The 15-minute reconciler selects PRs that have no report for their current head, or a recent head commit, instead of using updated_at.
• Each PR is reconciled under its own deadline and failures no longer abort the run; the run fails only if every attempted PR failed.
• Publishing is a no-op when a gate's evidence is unavailable and a report for the same head already exists, and a comment without a benchmark marker is no longer rewritten on every run.

why

• #3381 (from a fork) never received the gate: the coordinator logged "No open pull request is associated with 497b3a2…", so quality-report was skipped.
• The scheduled safety net could not recover it. updated_at is advanced by the gate's own labels/comments and by Mergify/Codecov/CodeRabbit, so 163 of 165 open PRs were selected although only 11 had a commit in the last 24h. The run hit its 25-minute timeout, logged context deadline exceeded for dozens of PRs, and never reached the later ones.
• PR #3377 had quality:ready and quality:not-ready swapped every 2-3 minutes between 01:34 and 01:47. The inputs were static and the run logs had swallowed the error, so the root cause is not proven; unavailable gates are now logged and no longer overwrite a same-head report.

references

• Affected PR: #3381
• Follow-up worth considering: add pull_request_review_thread triggers to quality-signal.yml, since the schedule no longer sees thread resolutions on old PRs with no new commit.
• Not verified against live GitHub yet; after merge, dispatch quality-report.yml and confirm #3381 gets its comment and label.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • Quality reports now correctly associate fork-based pull requests with their head commits, including when standard commit lookup does not find them.
  • Scheduled reporting prioritizes open pull requests without a report for their current commit, as well as those with recent commits.
  • A failure to inspect one pull request no longer prevents others from being processed. Existing reports, comments, and labels are preserved when review evidence is unavailable.
  • Reports now identify unavailable review evidence, and partial processing failures no longer fail the entire run.
• Documentation
  • Clarified scheduled report selection and recovery behavior.

• Change the release "Bump Homebrew formula" step in .github/workflows/build.yml from brew tap homebrew/core to brew tap homebrew/core --force.
• Add a fix-log documenting the failure and fix.

why

The Homebrew preinstalled on ubuntu-latest was upgraded to the 7.0.x line, which now refuses a plain brew tap homebrew/core:

Tapping homebrew/core is no longer typically necessary.
Add --force if you are sure you need it for contributing to Homebrew.

The step exits 1 on that line, before brew bump-formula-pr runs, so no Homebrew PR is opened on release. This failed the v1.232.0 release bump.

brew bump-formula-pr is a developer command that edits the formula .rb, so it genuinely needs homebrew/core checked out as a local tap (established across v1.228.0-v1.231.0: without the tap it fails "No available formula with the name atmos"). We do need the tap for contributing, so --force is the path Homebrew's own error message points to.

This step only runs on release: published, so PR CI cannot exercise it - the next release is the first real confirmation.

references

• Failing run: https://github.com/cloudposse/atmos/actions/runs/38333322212/job/115087877491
• Prior fixes in this saga: docs/fixes/2026-09-28-homebrew-bump-brew-not-on-path.md, docs/fixes/2026-10-09-homebrew-bump-needs-core-tap.md
• Fix-log: docs/fixes/2026-10-13-homebrew-bump-tap-core-force.md

Summary by CodeRabbit

• Bug Fixes
  • Updated the Homebrew release workflow to handle tapping homebrew/core with Homebrew 7.x, preventing the release step from failing.
• Documentation
  • Added a note describing the release-workflow issue and a possible alternative if similar failures recur.

Completes the remaining work for the ci automation module in one PR (no new YAML step types, per review):

• Fork-aware posting gate. ci.context.pr.fork is read from the GitHub event payload (pull_request.head.repo, and workflow_run.head_repository for workflow_run events) and from ATMOS_CI_PR_FORK on the generic provider. Under pull_request_target and workflow_run, comments and checks are now held only for fork pull requests; same-repository pull requests post normally. ci.allow_unsafe_fork_execution still overrides.
• Report templates. ci.summary(template=, data=) and ci.comment(template=, data=) render a file under ci.templates.base_path with the same engine as the built-in plan summaries; ci.summary.template and ci.comments.template (declared in the schema but unread until now) are the defaults when a call passes only data. Backed by templates.RenderReport and Reporter.RenderSummary/RenderComment.
• Container image reporting through the seam. Image summaries from atmos container build/push go through ci.Reporter: the job summary as before, plus one upserted pull request comment per image (keyed container:image:<image>) when ci.comments.enabled is on. The Markdown can be overridden with ci.templates.container.image; the embedded default is byte-identical to the previous renderer (golden tests).
• Hygiene. The terraform/helm/helmfile/kubernetes plugins use the exported ci.*Enabled helpers instead of private copies; the generic provider reads ATMOS_CI_OUTPUT/ATMOS_CI_SUMMARY at call time; dead providers/github/loggroup.go removed.
• Docs: ci, ci.summary, ci.comment, ci.check reference pages, the CI templates/summary/comments configuration pages, the container component page, the environment variable table (ATMOS_CI_PR_FORK), the changelog post (new section), and the PRDs (script-ci-module.md, interfaces.md, generic.md, github/provider.md, new providers/container.md).

why

These were the items left in the PRD's "Remaining implementation work" after #3307. Keeping them in the stack follows the repository rule that unmerged implementations are finished in their PR stack rather than tracked as issues. The fork refinement removes the one case where the previous gate blocked a legitimate workflow (base-checkout code commenting on a same-repository pull request under pull_request_target).

references

• Stacked on #3307 (osterman/starlark-ci-module) → #3298 → #3296.
• Remaining in the PRD, out of scope here: YAML step types for CI reporting, and an explicit opt-in to post for real from a workstation.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added customizable templates for CI summaries and comments, including container image reports. Container builds and pushes can publish per-image summaries and, when enabled, pull request comments.
  • CI scripts can render summaries and comments from templates and supplied data.
  • Pull request context now identifies fork-origin requests. On elevated events, comments and checks are held for fork pull requests unless unsafe fork execution is enabled; same-repository pull requests can post normally.

• Bug Fixes

  • Generic CI output and summary writers now use the current environment settings when called, so changes made after initialization take effect.

Fixes from a field test of the native CI reporter (#3298) and the fork-aware gate, templates, and container comments in #3308.

• Fork posting gate. The pull request number under pull_request_target and workflow_run now comes from the event payload (GITHUB_REF is the base branch there, so the headline same-repository case never posted). A fork is a head/base full_name mismatch; a deleted fork or unreadable payload is held, and a repository that is itself a fork is no longer penalised. Native Terraform comments and statuses go through ci.Reporter, so the gate applies uniformly, and env, path, and SARIF writes are held for fork pull requests under elevated events. ATMOS_ALLOW_UNSAFE_FORK_EXECUTION sets ci.allow_unsafe_fork_execution, as the docs already claimed.
• Commit comments. CommentRequest.Target (auto, pr, commit) with a CommitCommenter capability, a GitHub implementation, ghtest routes, and a generic preview. auto posts to the pull request when known and to the commit otherwise, so a push run no longer fails for lack of a pull request.
• Gate and output hygiene. Receipts name ci.enabled when the master switch is off (the warning previously blamed a per-feature flag the user had on). Annotations and ::add-mask:: go to stderr; log-group markers go to stdout to bracket command output; ::add-mask:: was being masked by Atmos before it reached the runner. Repeated ci.base() calls no longer stack duplicate safe.directory entries. Nested log groups render a heading instead of a nested ::group::. behavior=update requires a key, and a local update with no prior comment fails like GitHub. Check updates send the id, and DetailsURL is always filled.
• Invalid API URL is a hard error in the terraform --ci flow, not a cached warning. The native-ci fixtures point at an unroutable GITHUB_API_URL so their fake tokens can never reach api.github.com.
• Container image comments. A comment is attempted only when ci.comments.enabled is on (the gated write used to dump the full image summary into the log as a preview), keyed by registry/repository so pushes update one comment, truncated at 65,000 characters, with failures at Warn. The two near-duplicate implementations and their 667-line mocks collapse into pkg/component/container/imagesummary.

why

Every item was found by reading the code against its docs and then reproduced with a failing test before the fix. The fork gate as merged in #3308 did not post for the one case it was built for, and failed open for the one case it had to close. The rest are the differences between what the CI configuration pages promise and what a script author actually sees.

references

• Stacked on #3308 (osterman/ci-fork-templates-hygiene) in GitHub stack #3338; the ci module host wiring, step library, and documentation follow in #3319, #3320, #3337, and #3321.
• Fix record: docs/fixes/2026-10-08-stack-field-test-fixes.md (lands with the documentation pull request).
• Decisions recorded in the plan: fork gate scope (D1), fork definition (D2), payload number (D3), native plugins through the reporter (D4), hard error on an invalid URL (D6), forced CI mode (D7), container comment keys (D8), workflow-command output streams (D9).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added CI support for pull request and commit comments, including automatic comment targeting and keyed updates.
  • Container builds and pushes can publish image summaries to CI job summaries and, when enabled, post grouped comments by image repository.
  • Added controls for fork-related CI writes and clearer warnings when unsafe fork checkout is allowed.
• Bug Fixes
  • Invalid CI provider URLs now fail the command instead of being treated as warnings.
  • Improved CI output formatting, check-run details, and reporting of skipped uploads.

Fixes from a field test of the Starlark ci module (#3307) and the standalone script and custom-command input surface (#3261 through #3276).

• Host wiring. Parallel and matrix script children in custom commands and workflows received ci.NewReporter(nil), so under GitHub Actions every gate read as off, warnings named flags the user had enabled, and comments and checks never posted. Both control adapters now pass the configured reporter, the engine warns when a host supplies none, and host-wiring tests cover standalone, direct step, workflow, hook, parallel, and matrix.
• ci.comment(target=) (auto, pr, commit), returned as .target. Annotate rejects line without file and end_line before line. Check handles send the id on update and expose the details URL.
• Templates. ci.summary(data=...) and ci.comment(data=...) require template=; there is no configuration default for scripts. Rendering uses missingkey=error, so a typo'd key fails naming the key; a missing template names the resolved path and ci.templates.base_path; a configured but missing ci.templates.container.image is an error.
• Ctrl-C cancels the script, runs defer calls with the documented 30 s grace, then exits 130. main.go used to exit before any context was cancelled.
• Standalone scripts. #!/usr/bin/env -S atmos <flags> and .STAR are recognized; atmos - on a TTY says it is reading stdin; cli.flag rejects a default outside choices and checks an explicit empty value; --help ends the script; a relative script path resolves against the directory the user stood in before --chdir; atmos.tf shares the terraform binding; exec.run, component.exec, and atmos.* accept output="viewport".
• Custom commands. type: int flags parse base-10 (010 is 10, 0x10 is rejected); a wrong-typed default stubs the command with a warning naming the flag instead of silently becoming "" or false; an argument with neither required: nor default: is required again; !literal is honored on plain-string steps, command-level env, parallel and matrix env, and timeout; unsupported fields fail config load naming the field; !include.raw is used exactly as written and the template-error hint for included scripts no longer suggests a tag that cannot be applied there.
• A shared retry predicate so retry.conditions mean the same thing in every host (used by the next pull request), tighter ErrorIs assertions in the script tests, and new acceptance suites starlark-ci.yaml, starlark-inputs, and starlark-literal-invalid.

why

The host-wiring gap meant the ci module worked in exactly the places its unit tests mocked and not in the parallel steps a real pipeline uses. The input fixes close the differences between the documented contract (literal.mdx, cli.flag, ctx.flags, defer.mdx) and the shipped behavior; each was reproduced with a failing test first.

references

• Stacked on osterman/ci-fork-gate-commit-comments in GitHub stack #3338.
• Fix record: docs/fixes/2026-10-08-stack-field-test-fixes.md (lands with the documentation pull request).
• User decisions: no configuration default for script templates; explicit target=; viewport added alongside stream and capture.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added live viewport output for supported scripts and process commands, with standard streaming as a fallback.
  • Expanded CI scripting with templated summaries and comments, pull-request or commit comment targets, and reporter support in nested steps.
  • Added the atmos.tf alias and improved standalone script discovery, including case-insensitive extensions and more flexible shebangs.
• Bug Fixes
  • Integer flags now parse base-10 values; invalid defaults, out-of-choice values, and explicitly empty constrained choices are rejected.
  • Standalone scripts retain their original path when --chdir is used. Ctrl-C runs deferred cleanup, and help exits before later script actions.
  • Literal YAML values are preserved, and retry conditions can match error messages or captured process output.
  • Command arguments without a default or explicit optional setting are now required.
• Documentation
  • Updated CI function guidance and examples for comment targets, templates, and annotation validation.

Align CI, step, hook, and script documentation with the field-test fixes. Clarify template defaults, the ninth-hook recursion boundary, stdout log-group markers, and image-comment commit fallbacks and permissions. Move detailed CI script guidance into the skill reference to keep the main skill within its size limit.

why

Keep the documentation corrections separate from the Scripting navigation and URL migration, with each PR below 150 changed files.

validation

Full documentation production build passes. Current-head CI and CodeRabbit verification are pending.

references

• Base: #3320
• Next: #3321
• Part of GitHub stack #3338

Summary by CodeRabbit

• Documentation
  • Added guidance for script-based CI summaries, comments, statuses, environment exports, and fork pull request safeguards, including when reporting is held and how the safety gate can be bypassed.
  • Expanded automation references for script inputs, flags, output modes, templates, retries, timeouts, cancellation, Git hooks, and computed YAML values.
  • Clarified CI permissions and comment targets, as well as command-specific configuration and behavior.

Label the sidebar and landing page Scripting, introduce Atmos Automation Language once, and move the guides to /scripting with redirects from the previous URLs.

Rewrite the guides to explain concepts and syntax before examples. The hooks guide covers component, scaffold, and Git hooks, including events, inputs, and failure behavior. CLI examples lead with executable commands such as ./myapp and explain arguments, flags, and help directly.

why

Make scripting easier to find and the guides easier to use. Show where each feature belongs and how to run it before introducing a larger example.

validation

The full website build passed, as did navigation and documentation checks. Existing unrelated CI-page anchor warnings remain. Current-head GitHub checks and CodeRabbit approval are pending. No coverable Go changes.

references

• Top of GitHub stack #3338; based on #3337.
• Broader CI and field-test documentation is in #3337. This PR contains 117 changed files.

Summary by CodeRabbit

• Documentation
  • Reorganized the scripting guides around Starlark, with expanded guidance for workflows, custom commands, lifecycle hooks, testing, and standalone CLI apps.
  • Clarified custom-command argument behavior, including required and optional arguments, default values, and handling of commas, empty strings, and non-ASCII text.
  • Updated scripting documentation links and navigation throughout the site, including related guides and blog posts.

• Add the embedded Starlark runtime, including parallel function tasks, retries and timeouts, component and hook interfaces, subprocess execution, tool dependencies, and standalone-file detection.
• Build Atmos helpers from an injected immutable command catalog in pkg/flags. Keep independent Atmos, logging, and regex bindings in stdlib subpackages; the CLI installs its registered command metadata in #3266.
• Mask registered numeric and boolean secrets, plus automatic step/task context, before sending structured log fields to text or JSON sinks. Preserve native types for unmasked scalars.
• Make component-cache waiting cancellable. Document that lazy ctx.component attributes use the invocation context and that components.get supplies task-specific resolution deadlines. Use portable files in dialect regression tests.

why

Keep interpreter behavior and language bindings independently testable before wiring them into commands, workflows, and hooks. Reuse registered command metadata instead of maintaining a parallel list of commands and flags.

validation

• Runtime, standard-library, and flag tests passed with race detection; scoped lint and the full binary build passed.
• Regressions cover scalar and context masking, component-cache cancellation, task deadlines, retries, command metadata, and portable module paths.
• CI, Codecov patch coverage, and CodeRabbit approval must be verified on the rebased head.

references

• Part of GitHub stack #3338: #3263 (execution support) → this PR (runtime) → #3266 (CLI integration) → #3261 (declared inputs and documentation).
• Architecture and component deadline behavior
• Registry and cancellation fixes

Summary by CodeRabbit

• New Features
  • Added a Starlark scripting engine with standalone script detection, parallel tasks, retries, and dry-run support.
  • Scripts can run Atmos commands, execute processes, read files, resolve components, install tools, and use logging and regex utilities.
  • Added command and flag discovery for scripts, plus structured task output and cancellation support.
• Documentation
  • Added Starlark runtime guidance and notes on component resolution and runtime behavior.

• Introduce Atmos Automation Language, a Python-like language built on Starlark, with focused executable-script, custom-command, and lifecycle-hook examples and real casts.
• Integrate embedded Starlark into custom commands, workflows, hooks, test steps, and standalone executable scripts, preserving component context, source paths, retries, dry-run behavior, and masked streaming output.
• Supply the runtime command catalog from the fully registered CLI, including aliases and native flag spellings. The shared catalog and independent standard-library bindings are reviewed in #3264.
• Keep tool-version coordination locks in the XDG data directory, keyed by canonical manifest paths, so reads leave project directories untouched. Native filesystem metadata coordinates relative, symlinked, and case-variant aliases; known case-sensitive filesystems retain independent locks. Unknown filesystems conservatively share locks across case variants without changing manifest paths.
• Fix integration defects found with real subprocesses, composed YAML, and PTYs. Update cast-authoring skills to validate recordings with Starlark and remove NOTICE generation's anonymous metadata request in PR CI.

why

Reusable scripts need the same command definitions and execution policies as the CLI. Final-build validation exposed context, environment, source-provenance, masking, and test portability gaps that unit mocks had missed.

validation

• Touched-package tests, CLI regressions, build, lint, and website build passed locally. Repeated step-suite race tests passed.
• Real subprocess tests verify resolved step environment precedence in sequential and parallel component.exec calls.
• Field tests cover dry-run side effects, source paths, composed YAML, live terminal output, split secrets, and toolchain path aliases. Platform-specific lint and cross-compilation passed.
• CI, Codecov patch coverage, and CodeRabbit approval must be verified on the rebased head.

references

• Implementation layer of the Starlark stack, based on #3264 (runtime), which builds on #3263 (shared execution support). Standalone declared command interfaces, direct parsed-input context, documentation navigation, and CLI acceptance fixtures are in #3261 above this PR. Part of GitHub stack #3338.
• PRD
• Final field-test fixes
• Race and coverage validation

Summary by CodeRabbit

• New Features
  • Added Atmos Automation (Starlark) support for standalone scripts, custom commands, workflows, lifecycle hooks, and test steps, with parallel tasks, retries, and structured results.
  • Added examples and terminal recordings for scripts, custom commands, ownership checks, and release planning.
  • Moved tool-version lock files outside project directories.
• Bug Fixes
  • Improved secret masking across streamed output and applied configured masking to command output.
  • Embedded scripts are validated before execution, and dry runs parse scripts without running them.
  • Improved workflow include path resolution and test-failure summaries.
• Documentation
  • Expanded guidance for Starlark, script paths, terminal settings, and cast validation.

• Let standalone scripts define arguments, flags, and help through cli.command, cli.arg, and cli.flag, reusing native Atmos flag definitions, StandardParser, its registry, and positional-argument validation. Help and input validation finish before the main callback runs.
• Give custom-command and workflow scripts direct immutable ctx.flags and ctx.arguments, preserving parsed types through parallel, matrix, and test children. Remove the capacity example's environment mapping and regenerate its cast.
• Make /automation the documentation home for Atmos Automation Language, with dedicated reference guides for the language, custom CLI apps, custom Atmos subcommands, workflows, lifecycle hooks, and testing. Link the homepage automation card to this hub, keep reference navigation inside the docs, and embed three focused casts.
• Clarify custom CLI apps versus YAML-defined custom commands, add outcome-focused chapter introductions and a separate interpreter announcement, demonstrate styled UI output in the focused examples and regenerated casts, and explain why Starlark provides a focused shared automation language.
• Add CLI acceptance coverage, disposable fixtures, and snapshots for the integration in #3266, plus a declared-interface executable example.

why

Small scripts should share the CLI's parsing and validation behavior, and embedded scripts should receive inputs Atmos already parsed. A dedicated documentation entry point connects standalone programs, project commands, hooks, and workflows to the same language and reference.

validation

• Behavioral and acceptance tests cover declared arguments and flags, generated help, validation, immutable inputs, and typed values through sequential, parallel, matrix, and test steps.
• Targeted race tests, scoped lint, schema validation, and the production website build passed. Cast validation and browser checks passed.
• Review corrections cover links available at this stack layer, symlink module paths, serialized script assertions, and recorded UI output.
• CI, Codecov patch coverage, and CodeRabbit approval must be verified on the rebased head.

references

• Part of GitHub stack #3338: #3263 (execution support) → #3264 (runtime) → #3266 (integration) → this PR (declared inputs, documentation, and acceptance coverage).
• Declared command inputs
• Automation documentation hub
• Final field-test record

Summary by CodeRabbit

• New Features
  • Run standalone Starlark scripts as CLI apps with declared positional arguments and typed flags, generated help, and input validation.
  • Access parsed arguments and flags in scripts, custom commands, and workflow steps, including parallel and matrix tasks.
• Improvements
  • Starlark limits excessive recursion and presents clearer, more concise traceback details.
  • Standalone scripts show the local metrics summary only when explicitly enabled.
  • Starlark step output defaults to raw output without labels; labels can be enabled in configuration.
• Documentation
  • Added guides and examples for Starlark apps, custom commands, workflows, hooks, and testing.

• Add an Automation Functions reference under /functions/automation, next to YAML and Template Functions, with one page per function. It covers the cli.* declarations, every atmos.<command> wrapper (aliases are listed on their main command's page), components.get, component.exec, exec.run, steps.task, steps.parallel, fs.read_file, json.*, regex.*, dependencies.tools, each ui.* and log.* function, and the built-in values (ctx.*, env, output, print, load). Every page has usage, arguments, return values, and at least one example.
• Add a Language Reference under /automation/reference covering lexical elements, data types, expressions and operators, statements, built-in functions, methods, the execution model, and differences from Python.
• Rework the Custom CLI Apps introduction so it leads with what Atmos adds on top of Starlark: running Terraform, Helm, Kubernetes, and other components, building and pushing images, pinned tools, identities, stack configuration, parallel work, masked output, and AI skills. Each capability links to its function page.
• Link the Built-in helpers table in the language guide to the new pages.

why

The automation docs were guides only. Users and agents had nothing to look up for exact signatures, defaults, return values, or language rules. Signatures were taken from the Go source, and examples were run against the interpreter built from this stack.

references

• Stacked on #3261. It is split out so each PR stays under CodeRabbit's 150-file review limit.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Standalone scripts can now read source from stdin, with support for script arguments and interpreter selection.
  • Added the errors.build helper for reporting script failures with structured details.
  • Added extensive reference documentation for the Automation Language, its built-ins, data types, execution, and available functions.

• Documentation

  • Expanded guides and examples for workflows, custom commands, lifecycle hooks, testing, and standalone scripts, including passing values between workflow steps.

• Support !literal in atmos.yaml, and honor it on step fields: script, command, interpreter, working_directory, and individual env values. This works in custom commands, workflows, hooks, and parallel and matrix children. Tagged values are never template-rendered at run time, and markers are recorded only on step mappings, so vars, settings, and env maps are unchanged.
• Render only declared environment values. The ambient process environment now reaches child processes unchanged, where before a value containing braces broke script steps or was rewritten.
• Pass custom-command arguments through losslessly, so commas are no longer split. Support type: int flags, reject unknown flag types, and allow optional arguments without a default.
• Enforce timeout: on script, shell, atmos, and tflint steps, including workflow container paths. Reject unknown output: modes.
• Render parallel and matrix children with the parent's template functions and pass count. Template errors name the step, field, and included file, with a hint pointing to !literal.
• Give container steps the shared command output defaults: raw output, no labels.
• Add docs, agent skill updates, a blog post, the fix log, and the Starlark stack definitions PRD.

why

A field test of Atmos Automation Language in custom commands and workflows found step definitions that silently changed user data, and Starlark source containing {{ could not be written at all. Details are in docs/fixes/2026-10-04-literal-steps-and-custom-command-inputs.md.

references

• Stacked on #3274, which is stacked on #3261. The stack is split so each PR stays under CodeRabbit's 150-file limit.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added integer flags for custom commands, with whole-number defaults and integer values in templates and scripts.
  • Optional command arguments can be omitted and resolve to empty strings; argument values preserve commas, empty strings, and non-ASCII text.
  • Added !literal support for step fields and declared environment values, allowing template-like text to pass through unchanged.
  • Added enforced step timeouts for supported step types, including across retries and backoff.
  • Added validation for supported step output modes and JSON-formatted structured script outputs.
• Bug Fixes
  • Improved template rendering for parallel and matrix child steps, and clarified handling of inherited environment values.

Expose the registered Atmos step library through the shared pkg/automation Go API and Starlark steps.* bindings. Scripts can use prompts, HTTP requests, containers, archives, and the other registered handlers, with values, metadata, and named outputs available to subsequent calls.

Add lazy JSON decoding through result.data while preserving raw process stdout/stderr and step value. atmos.list, atmos.describe, and configuration getters default to captured JSON; explicit format/output choices still apply. Add --format=json to the CLI configuration getters without changing their raw-output default.

Expose timeout and retry options on exec.run and component.exec through a shared Go execution policy. A timeout covers all attempts and backoff; retries apply to checked ordinary nonzero exits and can match output conditions.

Document the APIs and restrictions, update help recordings, and add changelog and roadmap entries. The enclosing runner still owns workflow scheduling, identity preparation, background jobs, and freshness policies.

why

Scripts should reuse Atmos's step handlers and execution controls, and inspect structured command results without repeating JSON parsing or subprocess policy. Language bindings convert arguments and results; the shared Go interfaces own execution behavior.

validation

• Go build and CLI binary build
• Short tests across scripting, automation, flags, YAML, configuration getters, steps, and workflows
• Targeted standalone/custom-command/workflow regression tests
• Race tests for result decoding, query defaults, execution policy, and script dispatch
• Changed-code lint and commit hooks
• Real CLI query, decoding, timeout, help, and invalid-input smoke checks
• Production documentation build with MDX and link validation (identical read-only Git tag lookups cached locally)

references

Stacked on #3276 in the linear automation stack. This PR changes 81 files, below the 150-file review limit.

Summary by CodeRabbit

• New Features
  • Automation scripts can call registered workflow steps and use their returned values, metadata, and outputs in later operations.
  • Process calls support configurable timeouts and retries for eligible failures; captured output reflects the final attempt.
  • Automation query commands capture JSON by default and expose decoded results through data.
  • config get, stack config get, and stack get support --format/-f with raw and json output.
• Documentation
  • Added guidance and examples for step-library calls, structured query results, and process controls.

Allow git.hooks.<name>.steps to run named steps directly inside Atmos, including inline Starlark scripts. Existing command hooks remain supported; each hook selects one form.

Add fs.glob, fs.stat, fs.exists, and fs.readlink, backed by a shared Go filesystem interface. Add two inline repository checks to atmos.yaml: tracked symlinks and CLAUDE.md/agent-file byte limits.

Refresh the Git-hook, SDK, interpreter, workflow, scaffold, and lifecycle-hook PRDs to match the implemented API. Clarify the language overview and introductory announcement around writing and testing application and infrastructure delivery processes.

Why

Small repository checks can live beside their hook configuration, use structured errors, and share the same step library as other automation. Embedded scripts do not launch a second Atmos process. Hook arguments are available through ctx.args; steps share outputs and environment changes and stop on failure.

The sequence uses synchronous step execution and rejects workflow scheduler policies. Checks inspect working-tree contents, including unstaged changes. The existing pre-commit project setup retains its Bash checks because its pinned released Atmos binary predates these APIs.

Validation

• go build ./... passed. Configuration, generated-schema, and Git-hook package tests passed, including loader coverage for !literal, relative script includes, and imported hook definitions.
• Scoped atmos test and atmos test --full passed for automation, interpreter, Git-hook, step-runner, and schema packages.
• Focused race tests passed; filesystem and interpreter packages exceed 90% statement coverage.
• Real CLI smoke checks passed for both inline repository checks, hook arguments, byte sizes, literal script/environment values, and conflicting configurations.
• atmos lint --changed and production documentation build passed; PRD local links checked. The combined tree with the latest docs reorganization also passes navigation, command-introduction, and example-metadata checks, with no broken links or anchors.
• Scaffold hook regression verifies embedded Starlark, templated answers, generated-directory file access, shared step calls, and failure propagation.

References

Stacked on #3278. Includes configuration schema, function reference, Git-hook documentation, release announcement, and roadmap update.

Summary by CodeRabbit

• New Features
  • Git hooks can now run ordered Atmos steps, including inline Starlark scripts; existing command-based hooks remain supported.
  • Automation scripts can inspect local files with functions for matching paths, checking metadata and existence, and reading symlink targets.
  • Pre-commit checks flag broken tracked symlinks and instruction files exceeding their configured size limits.
• Documentation
  • Updated guides cover Git hook steps and filesystem functions, with examples and usage details.

Add !starlark to stack manifests. A scalar body uses return to produce typed configuration values from read-only ctx.vars, ctx.metadata, settings, environment, and component identity.

Expressions run after the existing YAML-function merges, resolve other computed values on access, and report circular dependencies. Literal source survives Go templates and retains its original filename and line. Configuration evaluation uses the interpreter registry with a separate typed-value capability and a 100,000-step budget.

Add the PRD, YAML-function reference, language-overview link, and roadmap milestone. Explain !starlark in the main Atmos Automation Language announcement, with a resource-tags example and a redirect from the consolidated post. This PR contains fewer than 150 changed files.

The schema ratchet classifies !starlark as stack-manifest-only. The lint and TFLint-hook CI jobs use the shared toolchain action to reuse the build job's verified binaries and avoid redundant release-attestation API calls.

why

Define tags, generated lists, and environment-specific values once, then compute them for each component's final configuration. The configuration host provides language builtins and JSON conversion; executable scripts provide commands, prompts, and the step library.

CI repairs

Reuse the shared CI toolchain cache, classify the new YAML tag for schema generation, stop SHA-pin lookups after API quota exhaustion, and pass large diagnostics between action steps through a file. Bound PR diagnostic tables, remove summed environment allocation capacities flagged by CodeQL, and make the controller-runtime NOTICE license URL deterministic. Incorporate the lower-stack formatting-bot commit while retaining the correct URL so GitHub’s combined stack checkout preserves it. Classify !starlark as forbidden in selection metadata because its context dependencies can require authentication or command execution.

validation

• Runtime, function registry, source preservation, YAML utilities, and dependency-selection tests.
• YAML/template regression tests, including inheritance, deferred map merging, cycle detection, and preservation of returned strings as data.
• Race tests for configuration evaluation and parallel component contexts.
• CLI checks for development and production overrides, existing YAML-function dependencies, help, and invalid source diagnostics.
• Repository Go build, scoped lint, formatting, navigation tests, and production documentation build.
• Offline SHA-verifier regression tests, environment merge tests, and NOTICE-generator tests.
• Complete selector package suite, including Starlark expression, multiline, and nested-map rejection.
• Focused script runner and standalone CLI tests; signed commit hooks; consolidated announcement HTML and redirect checks.
• Complete configuration-schema tests and schema regeneration (no artifact changes), cached-tool install regression, and workflow actionlint.

The full internal/exec short suite hit its 10-minute timeout. The scoped YAML/template regression suite passed.

references

• Stacked on #3283.
• PRD
• Reference

Summary by CodeRabbit

• New Features

  • Added !starlark expressions in stack manifests to compute typed configuration from merged component context. Expressions can reference other computed values, with dependency cycles reported as errors.
  • Terraform generators now use resolved component values when determining stack names, workspaces, and output paths.

• Documentation

  • Added guidance and examples for computed YAML values, including supported locations, evaluation behavior, and limitations.

• Bug Fixes

  • Preserved Starlark expressions through YAML and template processing so they evaluate against the final merged configuration.

Make script inputs, step execution, Git hooks, and computed stack values behave consistently across the CLI. This includes named usage errors and argument help, profile/identity forwarding, step-field rendering and validation, case-preserved variables and outputs, hook working directories and shim maintenance, and consistent Starlark context during stack discovery and generation.

Git hooks and standalone scripts now omit local resource-usage summaries when settings.metrics.enabled is unset. Existing Git command hooks also use this default; explicit configuration is preserved. Set settings.metrics.enabled: true or ATMOS_SETTINGS_METRICS_ENABLED=true to retain the summary. Edition pins do not gate this command-specific behavior change.

Stack naming templates reject computed identity values before functions can transform them. Varfile generation defers provisional workspace identity validation until computed values resolve, then applies the same final identity checks. Git hooks resolve inherited relative Git paths against the caller’s working directory before changing directories.

why

Field tests exposed cases where script flags affected Atmos itself, malformed steps ran too late to fail safely, hook installation was not idempotent, and computed values differed between describe and generation commands. Regression tests cover those behaviors and preserve raw script source until the correct evaluation phase.

validation

• Go build and changed-code lint pass; all signed-commit hooks pass.
• Unit tests pass for configuration, schema, script runtimes, CLI commands, and Git hooks; targeted step-validation tests pass.
• Starlark acceptance tests and four changed help/workflow golden cases pass.
• The intermediate fixture matches all 14 existing Starlark snapshots, so the new acceptance fixtures can follow separately.
• Documentation production build passes.
• Regression tests cover transformed computed identities, lazy template evaluation, and relative Git paths in command and step hooks. Focused execution, hook, and standalone-script tests pass.
• All 36 focused generator, workspace, and identity test functions pass with the race detector, including valid computed cases and forbidden identity transformations.
• Current-head CI, Codecov patch coverage, and CodeRabbit approval are pending.

references

• Stacked on #3294; part of GitHub stack #3338.
• Existing Git-hook announcement and roadmap milestone updated; no additional announcement.
• Migration: docs/prd/git-hook-steps.md#migration-and-editions.
• Field-test investigations: docs/fixes/2026-10-07-*.md.

Summary by CodeRabbit

• New Features

  • Custom-command and standalone-script help now describes positional arguments, required values, defaults, and allowed options.
  • Git hooks support configured steps, run from the repository root, and pass configured environment values through to steps. Uninstalling without hook names removes Atmos-managed shims, including orphaned ones.
  • Step and stack templates provide clearer validation and error reporting, including rendered output modes and retry settings.

• Bug Fixes

  • Invalid custom commands no longer prevent other commands from registering; warnings explain the issue, and invoking the affected command reports its error.
  • Explicit stack-file reads now report errors when files cannot be read. Starlark context values and stack locals are more consistent, and computed stack identities are rejected with a clear error.
  • Git hook resource-usage summaries are off by default unless explicitly enabled. Standalone scripts provide clearer flag and validation errors and pass active profile and identity selections to nested commands.
  • Git hook installation validates selected hooks before writing shims, repairs permissions on unchanged shims, and reports hook-specific errors.

• Documentation

  • Updated Git hook command help and related guidance.

Align the automation guides, function references, Git-hook documentation, and agent guidance with the validated runtime behavior. Add acceptance fixtures for standalone CLI inputs, step fields, Git hooks, computed YAML values, and stack identity validation.

why

Users need examples that show the exact input, output, working-directory, timeout, and error behavior they will get. The fixtures exercise those paths through the CLI, while the guides explain when templates and Starlark evaluate and how tool dependencies reach scripts.

validation

• All Starlark acceptance cases and four changed help/workflow snapshot cases pass.
• Documentation production build passes.
• Signed-commit hooks and whitespace checks pass.

references

• Stacked on #3295; 83 changed files.
• Runtime fixes are isolated in #3295 and child-process cleanup in #3294.

Summary by CodeRabbit

• Documentation
  • Clarified Git hook arguments, step execution, environment sharing, installation validation, and uninstall behavior.
  • Expanded Starlark guidance for available APIs, process results, retries, tool installation, standalone CLI flags, and command output.
  • Documented file-based configuration reads and clarified stack identity, script context, validation errors, and command usage.
  • Updated examples for component settings and Starlark values.
• Tests
  • Added coverage for Git hooks, Starlark scripts and steps, standalone CLI behavior, stack identity, and configuration edge cases.

Adds the ci module to the Atmos Automation Language, so any script (standalone, custom command, workflow, or hook step) can report into the CI provider that is running it with one call each, and renders the same calls locally when no provider is detected.

• ci.context (provider, event, SHA, branch, repo, actor, run ID/URL, elevated, pull request) and ci.base().
• ci.summary, ci.output, ci.env, ci.path, ci.mask, ci.annotate, ci.comment (keyed upsert, returns id/url/created), ci.check (handle with update), ci.group, ci.sarif.
• In CI every write honors the same ci.* configuration switches as native reporting; a gated-off call warns naming the flag and renders locally. Comments and checks are held on pull_request_target/workflow_run unless ci.allow_unsafe_fork_execution is set.
• SARIF output names the input file when rendered locally, including calls whose upload is disabled.
• Locally (no provider detected) every call renders on stderr through the script's own writer, so parallel-task prefixing and masking apply, and stdout stays clean for data.
• Docs: one reference page per call plus a module page, a "Reporting from scripts" section in the CI configuration docs, a note on atmos.ci distinguishing the subprocess wrapper, the PRD docs/prd/native-ci/framework/script-ci-module.md, a changelog post, and a roadmap milestone.
• Tests: mock-based unit tests for every builtin (argument validation, request mapping, gate warnings, lazy context, behavior inside frozen steps.parallel tasks, task-prefixed output), plus an integration test through the real generic provider.

why

Teams moving build/test/deploy pipelines out of GitHub Actions YAML into Atmos custom commands had no way to report back to the pull request without shelling out to gh and echoing into $GITHUB_ENV by hand, and none of that worked on a laptop. The seam this module calls landed in #3298; this PR is the user-facing surface.

Example (runs unchanged with atmos app test api --stack=dev in CI and locally):

tests = ci.group("test", lambda: exec.run(["go", "test", "./..."], check = False, output = "capture"))
ci.summary(body)
ci.comment(body, key = "app-test:" + component + ":" + stack)
ci.output("tested", "true" if tests.exit_code == 0 else "false")

references

• Stacked on #3298 (osterman/ci-reporter-seam), which is stacked on #3296.
• Remaining implementation work (YAML step wrappers, container summary through the seam, report templates, laptop opt-in to post, pr.fork, and housekeeping) is listed in the PRD under "Remaining implementation work"; per CLAUDE.md, no issues are opened for unmerged implementations.
• Also carries the fs.resolve and tilde-path support for fs.* functions (see docs/fixes/2026-10-07-fs-resolve-and-tilde-paths.md).
• Also carries the digest module (digest.sha256, digest.sha512, digest.sha1, digest.md5) and exec.which(name) (see docs/fixes/2026-10-07-digest-module-and-exec-which.md).
• Also carries defer(fn, *args, **kwargs): cleanup that runs last in first out when the script or task finishes, after fail() and cancellation (see docs/fixes/2026-10-07-defer-builtin.md).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added CI reporting for automation scripts, including summaries, outputs, annotations, comments, checks, and SARIF reports. Reports also render locally when no CI provider is available.
  • Added deferred cleanup, digest functions, executable lookup, and filesystem path resolution with home-directory expansion.
• Documentation
  • Expanded automation and CI references with usage guidance, examples, configuration behavior, and safety details.
• Bug Fixes
  • Improved local SARIF messages to identify the report file when its path is available.
• Workflow Guidance
  • Clarified how to track follow-up work before and after changes merge, and how to work with stacked pull requests.

• Use the existing CI Timing Summary workflow and stopwatch published output to invoke the Go quality reporter after Actions workflows finish, keeping stopwatch's TypeScript code and separate timing comment unchanged.
• Remove independent Quality Gate event triggers, make standalone benchmark reporting manual-only, and limit 15-minute recovery sweeps to open main PRs updated within 24 hours with early pagination stopping, selection logging, missing-timestamp validation, and no unchanged label writes.
• Update documentation and regression tests; validation passed: go test -tags mage ./magefiles/qualitygate/..., actionlint, and all commit hooks.

why

• Reduce duplicate reporter runs and API consumption causing installation rate-limit failures while retaining separate report implementations and scheduled recovery for missed events and late external results.

references

• Quality Gate rate-limit failure

Summary by CodeRabbit

• Automation
  • Quality reports are published after all workflows for a pull request have finished, including failed or canceled runs.
  • Scheduled checks reconcile open pull requests to main updated within the past 24 hours; manual checks cover all open pull requests to main.
  • Periodic reconciliation helps recover missed events and late results.
  • Benchmark reports now run manually using a completed benchmark run ID.
• Quality Reports
  • Existing labels and comments are left unchanged when they already match the report.

• Wrap the "Describe affected" benchmark table in the Quality Gate comment in a collapsed <details> block, like "All other benchmarks". The headline and per-snapshot warning lines stay visible above it.
• Remove the redundant github.com/cloudposse/atmos/ module prefix from benchmark metric names. Rows now read tests/benchmarks/CLI/DescribeAffected/... (sec/op).
• Pass the "CodeRabbit approval (current head)" gate when a bot account opens the PR (user.type == "Bot"): Renovate, Dependabot, the github-actions token, cloudposse-releaser[bot]. Evidence reads "Not required: PR opened by automation ()".

why

• The Describe affected table was the only uncollapsed section in the sticky comment. It showed 48 rows of runner noise even on markdown-only PRs such as #3369.
• Every metric name repeated the module path, which wrapped every row in the table.
• We don't require CodeRabbit approval on automated PRs, but the gate marked them "Not ready" (e.g. #3369 from cloudposse-releaser[bot]).

references

• Example comment: #3369 (comment)

🤖 Generated with Claude Code

• Bulk terraform deploy (--affected, --all, --components) now runs the same stored-plan check as single-component deploy, per component. Drift or a missing required plan fails the node before apply. A match applies the fresh plan.
• The per-node hook verifies on a copy with the node's own auth, so the fresh plan doesn't run with another node's credentials.
• The scheduler adapter carries the verified PlanFile into the executor. Before, the executor got a copy made before the hook ran, so the result was lost.
• Deploy nodes with provision.workdir that share a source dir take a lock on it, only while verification can write stored.plan.tfplan and new.plan there (storage configured, verify not off).
• Tests in cmd/terraform/verify_plan_bulk_test.go and pkg/scheduler/adapters/terraform_test.go, fix log in docs/fixes/.

why

• The bulk branches in terraformRunWithOptions return before verifyStoredPlanForDeploy, so only single-component deploy ever reached it. The download hook is warn-only and counts on that gate. Result: bulk deploy applied changed inputs and missing plans with exit 0.
• Behaviour now matches single-component deploy in every verify / required / storage combination, including the warnings single deploy already logs outside CI. No new flags or config.

references

• Closes #3396
• Ran: gofumpt, go build ./..., atmos lint --changed, go test -count=1 on cmd/terraform, pkg/scheduler, pkg/scheduler/adapters, pkg/ci/plugins/terraform/..., internal/exec, -race on cmd/terraform and the adapters. atmos test --full fails only in pkg/ci/startup and pkg/runner/step (PTY cast tests), same on a clean main at 753f2fe. Manual runs with local/dir and with github/artifacts in GitHub Actions: bulk drift and missing exit 1 with state untouched, matching applies in dependency order, single-component rows unchanged.
• Not run against aws/s3 or a real AuthManager, both covered by unit tests with stubs.
• Should be patch (bug fix, no new flag). Can't set labels from a fork.

Summary by CodeRabbit

• Bug Fixes
  • Bulk Terraform deploys now verify each component’s stored plan using that component’s authentication context and manager.
  • Deploys use the plan selected by verification, helping prevent execution with a missing or drifted stored plan.
  • Deploy workdir operations are serialized when they share a source directory and plan verification is enabled.
• Documentation
  • Updated Terraform deploy guidance to describe plan verification for both single-component and bulk deploys.

• Restore masked-inspection caches for !terraform.output, !terraform.state, and atmos.Component, partitioned by execution mode, configuration root, and authentication.
• Reuse deferred target describes and disabled-auth wrappers within an invocation. Capture only the goroutine header for cycle detection, avoiding repeated full-stack traces and preserving context identity on deep stacks.
• Share store values across caller stacks only when neither the effective auth configuration nor the store selects an identity. Preserve configured-identity and HEAD/BASE isolation.
• Avoid copying and decoding auth for every store cache lookup when component auth overrides are absent or empty. Hash the current global configuration directly; retain merge validation for nonempty overrides.
• Add regression tests and required CLI workloads for repeated functions and ambient store calls with dependents and YAML functions disabled. Use named constants for reference cache kinds and the inspection prefix.

why

Inspection cache bypasses and repeated deferred target describes multiplied lookup work. Profiling identified repeated full-stack capture for goroutine IDs. The follow-up report on #3353 exposed another multiplier: ambient store entries were split by caller stack, causing 660 backend reads for 11 keys across 20 stacks and three describe passes. After fixing that multiplier, rebuilding effective auth for empty component auth maps still added work on every cache hit.

The store workload is back to v1.229.0 speed. Rebuilt local field test using an identical current harness, twenty fresh-process samples per version in one series, Apple M4 Max, Go 1.27.1, GOMAXPROCS=2:

This PR is 19.7x faster than v1.231.0 and 2.75x faster than v1.232.0. The remaining 3.55% difference from v1.229.0 is below the 10% regression threshold.

The earlier ten-sample Terraform/component comparison measured 0.46957 s, versus 0.51650 s for v1.228.0 and 1.58634 s for v1.232.0: 9.09% faster than v1.228.0 and 70.40% faster than v1.232.0 (both p=0.00001083). These are separate field-test series, not stored CI snapshots.

The store read-count advisory remains: 22 versus 11 because HEAD and BASE have independent values. The fixture uses a loopback SSM service and fake ambient credentials; the customer's real AWS timing and effective default-identity configuration remain unverified.

Raw component describes can evaluate recursive stack locals, so those cache misses deliberately do not use singleflight. Concurrent cold misses may duplicate work while completed values are reused.

Validation: focused race tests cover cycle detection, deep-stack identity, inspection/cache/auth isolation, concurrent store credentials, and auth changes after cache hits. go build ./..., scoped atmos test, all new CLI scenarios via scoped atmos test --full, Mage tests, changed-file lint, all pre-commit hooks, and the website build passed. Earlier broad runs encountered startup-notice environment failures and terminal/CLI/workflow timeouts; full-suite success is not claimed. Details and reproduction commands are in the fix log.

references

• Closes #3353.
• Closes #3379.
• Follow-up evidence: #3353 (comment)
• Related cache precedent: #3354.
• Original changes: #3174, #3212.
• Fix log.

Summary by CodeRabbit

• Bug Fixes
  • Improved reuse of Terraform outputs, state, component references, and deferred lookups while keeping results separate across credentials, configuration, and inspection modes.
  • Inspection lookups continue to mask secrets, and incomplete or failed results are retried rather than retained as completed results.
  • Fixed cache invalidation and handling of empty component authentication settings.
• Tests
  • Added regression coverage and benchmarks for lookup reuse, credential isolation, retries, and cross-stack store reads.

Fixes from a field test of the automation step library, process cleanup, Git hook steps, and !starlark values (#3278 through #3296).

• Step fields. Every built-in handler declares its known fields; steps.shell(url="x") and steps.join(command="x") now error with the step type and the valid list instead of being accepted silently.
• retry.conditions apply to every step type (regexes over stdout, stderr, and error text; a non-matching failure stops at once); only http keeps its own status matching. Workflow and custom-command shell and atmos steps honor them too.
• Process cleanup. Shell and atmos steps, and every ShellRunnerWithWriters caller (custom commands, workflows, !exec, hook commands), run children in a process group that is torn down on timeout or cancel. A custom-command type: shell step with a timeout and a backgrounded grandchild used to hang Atmos forever on the pipe the orphan held; a regression test covers it.
• Timeouts report Step '<name>' (type <t>) did not finish within its timeout of <d> everywhere, not a bare context deadline exceeded; capture and stream on steps.<type> point to exec.run.
• !starlark. Selective commands (list … --columns, describe stacks --sections, describe component --query) evaluate only the config fields a value reads through ctx, by static reference analysis with a full-evaluation fallback; a component containing !starlark no longer runs sibling !exec values those commands never asked for. !starlark in atmos.yaml is rejected naming the file and key.
• Git hooks. Shell steps receive the hook arguments as "$@" and ATMOS_GIT_HOOK_ARGS; push-style hooks get their stdin in ATMOS_GIT_HOOK_STDIN and the first shell step still gets it on stdin; a later configuration source can switch a hook between steps: and command:; shims pin the atmos path at install and fall back to PATH; a prompt without a default fails with a hint; the failing step's exit code propagates.
• ATMOS_HOOK_DEPTH recursion guard (limit 8), profile and identity forwarded to script steps in custom commands, workflows, and hooks, and --format on config get, stack get, and stack config get registered through the standard flag parser with per-command environment variables.

why

The hang and the !starlark side effects are the two findings that could cost a user real time or run commands they did not expect; the rest turn documented promises (steps.run.mdx, retry.mdx, the Git hook pages) into enforced behavior. Each was reproduced with a failing test before the fix.

references

• Stacked on osterman/starlark-ci-module-inputs-fixes in GitHub stack #3338.
• Fix record: docs/fixes/2026-10-08-stack-field-test-fixes.md (lands with the documentation pull request).
• Decisions: hook recursion guard (D11), shim path pinning (D12), the generators' computed-identity behavior stays as documented (D10).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • config get, stack get, and stack config get support command-specific format environment variables; an explicit --format flag takes precedence.
  • Git hooks can pass their arguments and supported stdin to hook steps. Installed hooks can use the installing Atmos binary, falling back to the system PATH if unavailable.
  • Starlark references can evaluate only the configuration values they read; unsupported !starlark tags in atmos.yaml now produce an error.

• Improvements

  • Workflow retries can use configured conditions, and step timeouts now report the affected step type.
  • Hook execution stops with an error when nesting reaches the recursion limit.

• Forward the script and its arguments through ATMOS_USE_VERSION, version.use, and --profile re-execution.
• Accept Atmos global flags before the script path, such as atmos --chdir=dir tool.star. Extensionless paths run as scripts when they have an Atmos shebang.
• Treat a top-level None output as no output, so --help no longer prints null.
• Parse env-bound lists like command-line values. Reject flag and argument names that differ only in case, parse integers as base 10, and fail with a hint when true or false follows a boolean flag.
• Report user input mistakes as usage errors: exit 2, the usage line, a --help hint, and the missing argument named. Help marks required flags, choices, and env bindings. Tracebacks use relative paths.
• Document that the .star extension is optional when a script runs by path, and how to set editor file-type hints for Vim, Emacs, GitHub Linguist, and VS Code.

why

A field test of interpreter mode found that re-execution dropped the script, parsing quirks silently produced wrong values, and user mistakes looked like Starlark crashes. Details are in docs/fixes/2026-10-04-standalone-script-cli-behavior.md.

references

• Stacked on #3275 (!literal and step fixes), which is stacked on #3274 and #3261.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Standalone scripts now handle leading Atmos flags, --chdir, and version-pinned reruns while forwarding script arguments correctly.
  • Standalone CLI inputs support CSV-formatted string lists, base-10 integers, and environment values parsed like command-line values. Help output includes required fields, valid choices, and environment bindings.
  • Assigning None to top-level output produces no standalone output; None inside lists or dictionaries remains JSON null.
• Bug Fixes
  • Invalid standalone CLI input now produces clearer usage errors, without a Starlark traceback.
  • Script selection distinguishes missing .star paths from other paths and directories.
• Documentation
  • Expanded guidance for standalone CLI inputs, flags, help, errors, and output.

Terminate non-interactive subprocess groups when Atmos is canceled or a step times out. On Unix, children receive SIGTERM followed by SIGKILL after a bounded grace period if needed. Interactive children retain their terminal process group; Windows continues to terminate the direct child.

why

Canceling Atmos could leave commands and grandchildren running after a deployment stopped. Cleanup now completes before the canceled command returns, including when a parent exits before a grandchild that ignores SIGTERM.

validation

• Process and signal packages pass race tests; Windows process vet passes.
• Regression tests cover cancellation, deadlines, stubborn grandchildren, terminal input, exit cleanup, and background output pipes.
• Go build, changed-code lint, and all commit hooks pass.

references

• Stacked on #3286; part of GitHub stack #3338.
• Investigation and limits: docs/fixes/2026-10-07-child-process-group-signal-propagation.md.

Summary by CodeRabbit

• Bug Fixes
  • Canceling a command or exiting Atmos now also terminates its descendant processes on supported Unix systems, reducing the chance of leftover processes.
  • Commands with terminal input and Windows commands continue to use direct-child termination.
  • Background processes holding command output open no longer cause successful commands to hang or fail.

Foundation for exposing the native CI surface to the automation language (the Starlark ci module lands in the next PR of this stack). No Starlark in this PR.

• ci.Reporter (pkg/ci/reporter.go): one injectable seam with Summary, Output, Env, Path, Mask, Annotate, Comment, Check/UpdateCheck, Group, SARIF, Context, Base, WithOutput. Every write honors the same configuration switches as native reporting (ci.enabled plus the per-feature flag) and returns a Receipt saying where it landed (Provider, Local, Gate). A gated-off call in CI falls back to the local rendering instead of silently doing nothing. Under pull_request_target/workflow_run, comments and checks are held unless ci.allow_unsafe_fork_execution is set, mirroring the clone gate.
• Local parity: the generic provider is now the local renderer and the fallback for unknown CI (ci.ResolveProvider(); Detect() unchanged). It previews PR comments, prints annotations, log-group headings, SARIF notices, export lines for env/path, and reads ATMOS_CI_PR/ATMOS_CI_EVENT/ATMOS_CI_RUN_ID/ATMOS_CI_RUN_URL/ATMOS_CI_ENV/ATMOS_CI_PATH. It can be bound to a host writer (BindOutput) so script-step output keeps its task prefixing and masking. Unbound (the --ci plugin flow) it still emits raw text, so parseable output is unchanged.
• GitHub provider: honors GITHUB_API_URL and ATMOS_CI_GITHUB_API_URL (GHES), populates Context.RunURL, exports to $GITHUB_ENV/$GITHUB_PATH, and emits ::add-mask::.
• Test infrastructure: pkg/ci/providers/github/ghtest is a reusable fake GitHub REST API (issue comments, commit statuses, code scanning, pull requests, check runs) plus a SetEnv Actions fixture, modeled on pkg/oci/ocitest. The existing comments tests are migrated to it; the Reporter has end-to-end tests through the real GitHub provider against it.
• Cleanup: exported SummaryEnabled/OutputEnabled/ChecksEnabled/CommentsEnabled replace four identical private copies; the collision-safe heredoc formatter is now shared (ghactions.FormatValue) instead of implemented three times; comment validation is shared between providers; the terraform plugin's private run-URL helper is replaced by Context.RunURL; ci.comments.enabled schema comment corrected (it is opt-in).
• pkg/ui: Output.Markdown, Error, Errorf, Writef so bound renderings can draw markdown through a host writer.
• Hosts: script.Spec.CI is filled by standalone scripts, script steps, and workflow control steps.

why

Native CI can post plan comments, write summaries, set outputs, and create statuses, but only the built-in Terraform/Helm paths can reach those capabilities. A custom command or script that builds, tests, and policy-checks an application has to shell out to gh and echo into $GITHUB_ENV by hand. The next PR adds ci.* to the automation language; this PR puts every capability behind one seam with a local rendering so the same script runs unchanged on a laptop and in CI.

references

• Stack: based on osterman/starlark-field-test-docs (#3296). The Starlark ci module PR follows.
• PRDs updated: docs/prd/native-ci/framework/interfaces.md, docs/prd/native-ci/providers/generic.md, docs/prd/native-ci/providers/github/provider.md, docs/prd/native-ci/framework/implementation-status.md.
• Docs: new environment variables in website/docs/cli/configuration/ci/index.mdx and website/docs/cli/environment-variables.mdx.

Remaining implementation work for the stack is listed in docs/prd/native-ci/framework/script-ci-module.md under "Remaining implementation work" (no issues are opened for unmerged implementations).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added unified CI reporting for scripts and workflows, with local output when no CI provider is detected. Supported reports include summaries, outputs, environment and PATH updates, annotations, comments, checks, log groups, secret masking, and SARIF.
  • Added controls for enabling reporting features and restricting reporting in elevated pull-request events.
  • Added GitHub API URL configuration and CI run links for check results.
• Documentation
  • Updated CI configuration and environment-variable guidance, including comment opt-in behavior.
• Chores
  • Updated workflow security actions to version 2.22.0.

Prepare shared execution services for Starlark: streaming secret masking, file-relative YAML includes and script provenance, subprocess PATH lookup, retry clocks, and terminal-safe logging. Preserve renderer identities and resolve process working directories consistently.

Regex masking retains unfinished lines and bounded cross-line matches across writes; unbounded cross-line patterns are rejected. YAML aliases remain valid when command sections are decoded separately. Markdown rendering preserves masked text and ordinary text ending in spaces. Use local release and artifact fixtures for toolchain installation and update tests, and isolate viewport tests from logger state. Add the warning for oversized PRs. Bootstrap Atmos from its pinned release asset with checksum verification, remove network dependencies from acceptance fixtures, and give race jobs 60 minutes while preserving individual test timeouts. Public raw-file downloads no longer wait on unrelated GitHub REST quotas. On an installation-quota error, toolchain attestation verification can retrieve public evidence without credentials and verify it with the original artifact, signer, and predicate requirements. Invalid or incomplete responses still fail. The SHA checker stops further API lookups when its quota is exhausted and reports all unresolved references. Temporary Git fixtures disable background maintenance to prevent cleanup races. Command tests restore the previous logger level so shuffled tests do not inherit debug output. The S3 migration fixture pins its tools to avoid live version-list requests.

why

These services support the later runtime PRs and fix execution behavior for existing callers. Deterministic tests remove failures caused by public GitHub quotas and shared logger state.

validation

Focused Go tests, race tests, builds, and affected lint passed. Long-token and inherited-debug regressions failed before their fixes. The 19 CI-helper tests, four SHA-verifier tests, actionlint, a real bootstrap download/checksum check, configuration/masking/downloader/UI/toolchain-verification race tests, and offline acceptance checks passed. The attestation fallback has 87.3% local added-line coverage. The bootstrap passed in GitHub CI on Linux, Windows, macOS ARM, and macOS Intel before the final follow-up push. The Git fixture regression fails before the fix and passes afterward; provider race tests and 30 repetitions of the affected cleanup tests pass. The actual Floci S3 migration test passes with the pinned versions, including history, migrated state, and repeat-plan assertions. The logger-state regression fails before the fix and passes afterward; the full root command race suite passes with CI’s shuffle seed. All 26 updater tests pass at the root and stack tip with public HTTP blocked and race detection under CI’s Go version; the full toolchain package race suite passes too. The latest-pin success test failed before the fixture repair. Rebased onto main’s govulncheck fix (#3347) and removed the superseded Node SARIF workaround. The upstream govulncheck race tests and Mage target pass at both ends of the stack. Current-head GitHub CI, Codecov, and CodeRabbit verification remain pending.

references

• First PR in GitHub stack #3338; stack tip #3321.
• Execution fixes.
• Acceptance fixes.

Summary by CodeRabbit

• New Features
  • Added streaming secret masking across command output, terminal sessions, pagers, and captured errors—even when secrets are split across writes.
  • Improved YAML include resolution across working directories and configuration layouts, with local script-source tracking and support for clearing inherited commands using commands: !unset.
  • Added terminal query emulation when interactive input is unavailable.
  • Added checksum-verified Atmos bootstrap installation and public attestation verification fallback for GitHub quota limits.
• Bug Fixes
  • Improved command lookup using each invocation’s environment and working directory.
  • Corrected GitHub rate-limit handling for raw-content downloads and improved logger color behavior and Markdown rendering.
  • Retry operations now respond promptly when their context is already canceled.
• Documentation
  • Clarified requirements for custom multiline masking patterns.