Skip to main content

ci.group

The ci.group function runs a function inside a collapsible log group, so the runner's log view folds the noisy output under a single title. Locally, it prints a heading line before the function runs.

Usage​

ci.group(title, fn)

Arguments​

title
Required. The title shown on the collapsed group, as a string. An empty string is accepted.
fn
Required. A function that takes no arguments. Define a small wrapper function to pass arguments through.

Returns​

The value that fn() returns, so a group can wrap work whose result you need afterwards.

Behavior​

  • In CI, the group opens before the function runs and closes after it returns.
  • Locally, the call prints a heading line with the title and then runs the function.
  • In CI the call is gated by ci.groups.mode. When the mode is off, the call warns, renders a heading locally, and still runs the function. See gating.
  • The function always runs, whatever the gate says.
  • Groups do not nest. A ci.group call inside another group, or inside a group Atmos opened for a command, runs its function and prints a plain heading instead of opening a second group.

Examples​

Group a noisy command​

def install():
    return exec.run(["npm", "ci"])

ci.group("Install dependencies", install)

Use the result​

def count_stacks():
    return len(json.decode(exec.run(["atmos", "list", "stacks", "--format=json"], output = "capture").stdout))

total = ci.group("Count stacks", count_stacks)
ui.info("Found " + str(total) + " stacks")

Errors​

  • A missing title (the argument is absent) or a fn that is not callable fails with an argument error that names ci.group.
  • An error raised inside fn fails the script as usual.

Related​

  • ci describes the module and the shared behavior rules.
  • CI log groups configures how Atmos groups its own command output.