Skip to main content

atmos.ci

The atmos.ci function runs atmos ci through the current Atmos executable. Use it to check CI status, validate GitHub Actions workflow files, and manage the CI build cache from automation.

Usage​

atmos.ci(
    *positionals,
    flags = {},
    args = [],
    working_directory = ...,
    env = ...,
    output = "stream",
    check = True,
)

Subcommands​

Pass the subcommand and any positional arguments as strings before the keyword arguments. The call atmos.ci("validate", flags = {"format": "sarif"}) runs atmos ci validate --format=sarif.

SubcommandPurpose
statusShow CI status for the current branch.
validateValidate GitHub Actions workflow files.
cache restoreRestore the cache into the well-known cache directory.
cache saveSave the well-known cache directory to the CI cache.
cache listList CI cache entries.
cache deleteDelete a CI cache entry by key.
cache pathsPrint the cache key and paths, for use with actions/cache.

See the atmos ci command reference for the complete list of subcommands and flags. The ci command is experimental, and the cache group has its own page. The cache commands save and restore content only inside a supported CI provider, such as GitHub Actions. Outside CI they report that the cache is unavailable.

Arguments​

*positionals

(Optional) Strings placed on the command line right after ci, in order: the subcommand, its nested subcommand, and any positional arguments. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. A bare key such as "format" becomes --format, and registered shorthands resolve to their long form, so "k" resolves to --key for the cache commands. Other flags include --affected, --base, and --exclude for validate, and --path for cache save.

args
(Optional) A list or tuple of strings appended after the flags.
working_directory, env, output, check

(Optional) See atmos.run for process options and defaults.

Options other than the positionals are keyword-only.

Returns​

A result with stdout, stderr, and exit_code. See atmos.run for output and error behavior.

Examples​

Validate workflow files​

atmos.ci("validate", flags = {"affected": True, "base": "origin/main"})

This runs atmos ci validate --affected --base=origin/main and raises an error when a workflow file is invalid.

Validate a workflow directory and keep the result​

result = atmos.ci(
    "validate",
    flags = {"workflow-path": ".github/workflows", "exclude": ["**/legacy-*.yml"]},
    output = "capture",
    check = False,
)
if result.exit_code != 0:
    fail("Workflow validation failed:\n" + result.stderr)
ui.success("Workflow files are valid.")

The command writes its summary to standard error, so the message to show on failure is in result.stderr.

Save the cache at the end of a job​

atmos.ci("cache", "save", flags = {"key": "toolchain-linux"})

List cache entries as data​

entries = atmos.ci("cache", "list", flags = {"format": "json"}, output = "capture")
print(json.decode(entries.stdout))

Read CI status without failing the script​

status = atmos.ci("status", output = "capture", check = False)
if status.exit_code != 0:
    ui.warning("CI status is not available here.")

Some CI providers do not support the status query. The call then exits with an error that the provider does not support the operation.

Related​