Skip to main content

CI Log Groups Configuration

The ci.groups section of atmos.yaml controls collapsible CI log groups. When Atmos runs inside a CI provider that supports log grouping (GitHub Actions today), it folds its output into named, expandable sections — on GitHub Actions, the ::group::<name> / ::endgroup:: workflow commands. A single mode selects the grouping granularity.

Experimental

Quick Start​

atmos.yaml
ci:
  enabled: true     # master switch (required)
  groups:
    mode: auto      # auto | invocation | off  (default: auto)

With ci.enabled: true, grouping defaults to auto in a grouping-capable CI provider — you do not need to set ci.groups.mode at all.

Grouping modes​

CI providers do not support nested groups, so the mode is a single, mutually-exclusive choice of granularity:

auto (default)

The finest grouping that applies to each command:

  • Workflow / custom-command steps — one group per step, labeled with the step name.
  • terraform / tofu phases — separate groups for init and the main subcommand (plan / apply / destroy / …).

When a step runs atmos terraform apply, the step is one group and its internal phases stay flat inside it (the outermost group wins).

invocation

One group around each whole top-level atmos <command> run — including plain commands invoked directly from CI YAML (atmos describe, atmos vendor pull, a bare atmos terraform plan). Finer step/phase grouping is suppressed.

off
No grouping.

How It Works​

In auto mode a workflow renders as a list of expandable steps:

::group::deploy network
... `atmos terraform apply vpc` output ...
::endgroup::
::group::deploy cluster
... `atmos terraform apply eks` output ...
::endgroup::

…and a direct atmos terraform plan renders as its phases:

::group::terraform init
... provider/backend init ...
::endgroup::
::group::terraform plan
... the plan ...
::endgroup::

A few properties keep the behavior safe and unobtrusive:

  • No-op outside CI. When no grouping-capable provider is detected, or when mode: off, output is unchanged.
  • No nested groups. When a command invokes atmos again (a custom command calling another, a nested workflow, or a workflow step running atmos terraform apply), the child detects the open group and stays flat. You always get one level of grouping.
  • Secret-safe labels. Group labels go through the same masking layer as the rest of Atmos output. Invocation labels also omit flags, flag values, and anything after --.
Requirements

Grouping is emitted only when both ci.enabled is true and a grouping-capable CI provider is detected (GitHub Actions sets GITHUB_ACTIONS=true). Outside a supported provider it is a no-op.

Configuration Reference​

ci.groups.mode

Grouping granularity: auto, invocation, or off. Effective only when ci.enabled is true and a grouping-capable provider is detected.

Default: auto (when omitted)

Environment Variables​

VariableDescription
ATMOS_CI_GROUPS_MODEOverride ci.groups.mode (auto/invocation/off)