alai.toml¶

alai.toml marks a project, declares what it needs, and holds alai's settings. The file is TOML, and lives at the project root or is used as a user or system config file. Configuration covers where each config file is found and how its settings combine with flags and environment variables.

What a file can hold depends on whether it's the project's own alai.toml or a config file:

• Top-level keys and [[index]] are settings. Settings define how alai runs, and any alai.toml can set them. Each one also has an environment variable, and all but python_index have a command-line flag.
• [project], and everything under it, describes the project. Only the project's own alai.toml can have [project], never a user or system config file.

Every key below is optional, so an empty alai.toml still marks the project root. An unknown key or a value of the wrong type is an error naming the file, so a typo never silently does nothing. Keys are written in snake_case to match their kebab-case CLI options, such as link_mode and --link-mode.

# alai.toml

# Settings: Top-level keys come before any [table] in TOML
cache_dir = "~/.cache/alai"
link_mode = "auto"

# Index: Declares custom indexes in priority order
[[index]]
name = "internal"
url = "https://ansible-index.example.com/"

[[index]]
name = "mirror"
url = "https://alai-mirror.example.com/"
default = true

# Project: Only the project's own alai.toml can have these
[project]
collections_dir = "collections"
requires_ansible = ">=2.17"
collections = [
    "community.general>=9,<11",
    "ansible.windows",
    "corp.tools>=1.2",
]

[project.groups.test]
collections = ["ansible.posix", "community.crypto"]

[project.overrides]
"ansible.netcommon" = ">=6"
ignore_requires_ansible = ["some.collection"]

[project.sources]
"corp.tools" = { index = "internal" }
"corp.dev" = { path = "../corp.dev", editable = true }

# Never read by alai: Used to declare custom entries for future
# tools that may read alai.toml
[tool.my-ci]
deploy_target = "prod"

Settings¶

cache_dir¶

• Type: string, a path
• Default: $XDG_CACHE_HOME/alai, else ~/.cache/alai
• Flag: --cache-dir <dir>
• Environment variable: ALAI_CACHE_DIR

Where downloaded artifacts, extracted collections, and index metadata are kept. The data in this cache is shared by every project.

link_mode¶

• Type: string
• Choices: auto, clone, hardlink, copy or symlink
• Default: auto
• Flag: --link-mode <mode>
• Environment variable: ALAI_LINK_MODE

How files get from the cache into the collections directory:

• auto, the default: try clone, then hardlink, then copy, using the first that works.
• clone: a copy-on-write reflink, where the filesystem supports one.
• hardlink: the file shares its data with the cache, so editing an installed file in place also edits the cached copy (see below).
• copy: an ordinary copy.
• symlink: a link to the cached file, so the installed collection depends on the cache. Clearing the cache breaks the installed collection, and so does using it in an execution environment or container that doesn't have the cache. auto never picks symlink.

offline¶

• Type: boolean (TOML's true or false, not a string)
• Default: false
• Flags: --offline, --no-offline
• Environment variable: ALAI_OFFLINE, a boolean

Use only index data and collections alai has already cached, without connecting to any index. A command that needs something that isn't in the cache fails, saying what it couldn't find. Offline mode only applies to indexes over http:// or https://, as an index given as a file:// URL is read from disk either way.

python_index¶

• Type: string, an http:// or https:// URL
• Default: https://pypi.org/simple/
• Environment variable: ALAI_PYTHON_INDEX
• Flag: none

The Python package index that alai find reads ansible-core's and ansible-rulebook's own plugins from, as ansible.builtin and eda.builtin. The URL is the root of a simple index that serves its JSON form, as PyPI does and private indexes such as devpi, Artifactory and Nexus do. alai downloads each project's latest release from the index and keeps what it reads in the cache. See Finding plugins.

[[index]]¶

• Type: array of tables, one per index
• Default: none, and the built-in default index https://index.alai.sh/ is always searched last
• Flags: --index NAME=URL, which can be repeated, and --default-index [NAME=]URL
• Environment variables: ALAI_INDEX, holding NAME=URL values separated by whitespace, and ALAI_DEFAULT_INDEX, holding [NAME=]URL

An index to resolve collections from. Repeat [[index]] for more than one index, and they're searched in the order they're written, before the default index.

--default-index and ALAI_DEFAULT_INDEX replace the default index. Given a bare URL, the index keeps the name alai, so a mirror of index.alai.sh set this way still answers [project.sources] entries naming alai.

Configuration covers how the indexes from every level are combined into one list.

[tool]¶

alai never reads [tool] at any level, so other tools and scripts can keep their own settings under [tool.<name>] without alai flagging them as invalid.

Project¶

Only collections_dir has a CLI flag and an environment variable. The remaining options describe only what the project needs, so they can only be defined in that project's alai.toml. Managing collections covers how a project declares the collections it needs.

project.collections_dir¶

• Type: string, a path
• Default: collections in the project root for a playbook project, or a directory of its own in the cache for a collection project
• Flag: --collections-dir <dir>
• Environment variable: ALAI_COLLECTIONS_DIR

The directory the project's collections are installed into. Each collection is installed at <collections_dir>/ansible_collections/<namespace>/<name>. A value ending in ansible_collections is taken as its parent, as Ansible does with its collection paths. Where collections are installed shows an example layout.

A relative value in alai.toml is relative to the directory holding the file. A relative value from the flag or environment variable is relative to the current directory.

project.requires_ansible¶

• Type: string, a PEP 440 version specifier
• Default: none, so any ansible-core

The ansible-core versions the project targets, as a PEP 440 specifier such as >=2.17 or >=2.17,<2.20. The syntax is the same as requires_ansible in a collection's meta/runtime.yml.

A collection project declares its ansible-core versions in meta/runtime.yml instead, and setting project.requires_ansible there is an error.

project.collections¶

• Type: array of strings, each a requirement
• Default: none

The collections the project needs, as an array of requirements.

A collection project declares its dependencies in galaxy.yml instead, and setting project.collections there is an error.

[project.groups.<name>]¶

Collections only some workflows need, such as tests, in a table per group:

[project.groups.test]
collections = ["ansible.posix", "community.crypto>=2"]

Group names use lowercase letters, digits, - and _, starting with a letter or digit. alai sync installs the dev group with the project's collections by default and the others when asked for. See Groups for more details.

[project.overrides]¶

When a collection the project depends on has wrong metadata, [project.overrides] replaces it:

[project.overrides]
"ansible.netcommon" = ">=6"
ignore_requires_ansible = ["some.collection"]

Collection names contain a dot, so they must be quoted, as in "ansible.netcommon" = ">=6".

[project.sources]¶

Where particular collections come from, keyed by collection name. Collection sources covers each source type and when to use it.

[project.sources]
"corp.tools" = { index = "internal" }
# From the default index only, even if an earlier index has it too
"ansible.netcommon" = { index = "alai" }
"corp.dev" = { path = "../corp.dev" }
"corp.lib" = { path = "../corp.lib", editable = true }
"corp.net" = { path = "dist/corp-net-2.1.0.tar.gz" }
"corp.web" = { url = "https://artifacts.example.com/corp-web-1.4.0.tar.gz" }
"corp.win" = { git = "https://git.example.com/corp/windows.git", rev = "v3.0.0" }

When a collection's galaxy.yml has a placeholder version that its release fills in, set version = "<version>" on its source. The semantic version is used in place of the one in galaxy.yml, and works for a git source or a directory path source, editable or not. See Overriding galaxy.yml versions.

An entry applies wherever the collection appears, whether the project lists it in collections or another collection depends on it. Without an entry, a collection comes from the first index that has it (see Configuration). Naming the index yourself is also how to be sure a collection can't come from somewhere else that happens to have one by the same name.

Requirements¶

A requirement is a collection name followed by an optional version requirement, with the same syntax as ansible-galaxy's requirements.yml and galaxy.yml.

NAMESPACE.NAME[VERSION REQUIREMENT]

Version requirements¶

A version requirement is * for any version, or one or more clauses separated by commas that must all be met. A clause is an operator and a version:

Collection versions are semantic versions. A version in a clause can leave out its minor and patch parts, which count as 0, so >=9 is >=9.0.0 and ==9 is exactly 9.0.0. Pre-releases are supported, so >=2.0.0-rc.1 accepts 2.0.0-rc.1, any later release candidate and the final release.

The following forms aren't supported, and each has an alternative to write instead: