Skip to main content

ci.base

The ci.base function returns the base that Atmos uses for affected detection: the reference, commit, and target branch that the current run is compared against. Use it to scope your own checks to the same set of changes.

Usage​

base = ci.base()

Arguments​

The function takes no arguments.

Returns​

A struct, or None when no base can be determined:

ref
The base reference, such as "origin/main", as a string.
sha
The base commit that changes are compared against, as a string.
head_sha
The head commit of the run, as a string.
target_branch
The branch the change is headed for, as a string.
source
A string that says where the base came from, such as an event payload or an explicit setting.

Behavior​

  • In CI, the base is resolved from the provider's event data with the same rules that atmos describe affected uses, so a script and the native affected detection always agree.
  • Locally, the generic provider reads ATMOS_CI_BASE_REF. When nothing can be resolved, the call returns None.
  • The call only reads. It is not gated by any ci.*.enabled flag and never warns. On GitHub Actions with ci.enabled, it first marks the workspace as a git safe.directory so git can read it, once, without adding duplicate entries.

See the ci module for the shared behavior rules.

Examples​

Show what the run compares against​

base = ci.base()
if base == None:
    ui.warning("No base commit found; checking everything")
else:
    ui.info("Comparing " + base.head_sha[:7] + " against " + base.ref + " (" + base.source + ")")

Pass the base to a command​

base = ci.base()
args = ["describe", "affected", "--format=json"]
if base != None:
    args.append("--base=" + base.sha)
affected = atmos.run(args, output = "capture")

Errors​

  • A missing base is not an error. The call returns None, so check for it before reading the fields.

Related​