Skip to main content

atmos.pro

The atmos.pro function runs atmos pro through the current Atmos executable. Use it to lock and unlock stacks in Atmos Pro and to commit changes through the Atmos Pro GitHub App from pipeline automation.

Usage​

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

Subcommands​

Pass the subcommand as a string before the keyword arguments. The call atmos.pro("lock", flags = {"component": "vpc", "stack": "plat-ue2-dev"}) runs atmos pro lock --component=vpc --stack=plat-ue2-dev.

SubcommandPurpose
lockLock a stack so no other process can plan or apply it.
unlockUnlock a stack.
commitCommit changes through the Atmos Pro GitHub App.

See the atmos pro command reference for the complete list of subcommands and flags.

Arguments​

*positionals

(Optional) Strings placed on the command line right after pro, in order: the subcommand. Every value must be a string.

flags

(Optional) A dictionary of command-line options; see flag translation. For lock and unlock, the keys "component" and "stack" become --component and --stack, and shorthands such as "c" and "s" resolve to the long form. For lock, the keys "ttl" and "message" set the lock duration in seconds and the lock message. For commit, the keys "message", "all", "add", and "comment" control what is committed.

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​

Hold a lock while a script works​

atmos.pro(
    "lock",
    flags = {"component": "vpc", "stack": "plat-ue2-dev", "ttl": 300, "message": "Locked by release script"},
)
result = atmos.terraform("deploy", "vpc", "plat-ue2-dev", check = False)
atmos.pro("unlock", flags = {"component": "vpc", "stack": "plat-ue2-dev"})
if result.exit_code != 0:
    fail("Deploy failed with exit code {}.".format(result.exit_code))

Passing check = False lets the script release the lock after an ordinary nonzero deploy exit, because the language has no try/finally. A process-start failure, cancellation, or signal termination can still stop the script before unlock runs, leaving the lock until its 300-second TTL expires. Finish the work or unlock the stack before that TTL expires.

Commit formatted files​

atmos.pro("commit", flags = {"message": "terraform fmt", "add": "*.tf"})

This runs atmos pro commit --add=*.tf --message=terraform fmt, which stages changed Terraform files and creates the commit through the Atmos Pro GitHub App, so the commit triggers the next CI run. The Git index selects which paths the commit includes, including paths staged before this call; --add only limits what this call stages. Atmos Pro reads the contents of added and modified files from the working tree, so unstaged edits to an already staged path are committed too. Start from a clean index when the commit should contain only the formatted files. The all flag (--all) instead stages every change with git add -A, so use it only when the whole working tree belongs in the commit.

Continue when a stack is already locked​

lock = atmos.pro("lock", flags = {"component": "vpc", "stack": "plat-ue2-dev"}, output = "capture", check = False)
if lock.exit_code != 0:
    ui.warning("Could not lock the stack:\n" + lock.stderr)
note

In connected GitHub Actions pipelines, Atmos can obtain a bearer token through OIDC. For lock and unlock in other automation, supply a bearer token through settings.pro.token or ATMOS_PRO_TOKEN. The CLI sends that token with the API request; Atmos Pro determines whether it authorizes the request.

Related​