apt_repository
apt_repository adds a vendor's package source to a Debian or Ubuntu node:
one signing key and one source file in apt's deb822 format, and for a
private repository its login. Put the task before the
apt_package task that installs the vendor's packages.
On a node that uses dnf, dnf_repository does the
same.
- apt_repository:
name: docker
uris: [https://download.docker.com/linux/debian]
suites: ["{{ .node.distribution.codename }}"]
components: [stable]
signing_key_source: files/docker-apt-key.asc
- apt_package:
packages:
- {name: docker-ce, version: newest_when_first_installed}
On the node, the task writes:
/etc/apt/keyrings/docker.asc
/etc/apt/sources.list.d/docker.sources:
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: trixie
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
name is a repository name you choose. It is the base name of the files:
letters, digits, _, -, and ., the names apt reads from
sources.list.d. Each value of uris, suites, components, and
architectures is one word, and each can be a reference, such as the node's
release name above. A suite that ends in / is a flat repository and takes
no components.
Inputs
name(string; required): writes/etc/apt/sources.list.d/<name>.sourcesand/etc/apt/keyrings/<name>.asc, or<name>.gpgfor a binary keyuris(list of strings; required): omit with absentsuites(list of strings; required): omit with absent; a suite ending in / is a flat repositorycomponents(list of strings; optional): required unless the suite ends in /architectures(list of strings; optional)signing_key_source(string; optional): local signing key, relative to the project root, or to the role's directory inside a role; one of signing_key_source or signing_key_urlsigning_key_url(string; optional): HTTPS URL of the signing key, fetched and verified on the controller like download; may read vars, role inputs, loop items, and .node.namesigning_key_sha256(string; optional): the key's SHA-256 in hex; with signing_key_url, exactly one of signing_key_sha256 or dangerously_skip_checksumdangerously_skip_checksum(boolean; defaultfalse): true in place of signing_key_sha256: the key is trusted as it arrivesusername(string; optional): with password: the login for a private repository, written to/etc/apt/auth.conf.d/<name>.conf(root only, 0600) with one entry for each of uris; never in the source filepassword(string; optional): with username; must be a whole-value secret reference such as {{ .secrets.vendor_repository_password }}, or in a role one whole reference to an input declared secret: truestate(presentorabsent; defaultpresent): absent removes the source file, then the key, then the login file, and accepts only name and state; packages stay installed
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschange
What a dryrun reports
Supported; fetches and verifies a signing_key_url, then previews the key and source file; the next installation or upgrade in the job refreshes indexes.
Retries and time limits
Bounded automatic retries by default; retry: false turns them off.
The node task takes the time limits time_limit and time_limit_per_try; without them, the project's node_task_defaults apply. mmx describe-module task describes the settings every node task accepts.
Examples
Add a vendor's repository with a key from a web address
- apt_repository:
name: docker # a repository name you choose for the managed files
uris: [https://download.docker.com/linux/debian]
suites: ["{{ .node.distribution.codename }}"]
components: [stable]
signing_key_url: https://download.docker.com/linux/debian/gpg
# Replace with the SHA-256 of the signing key you have verified.
signing_key_sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
- apt_package:
packages:
- {name: docker-ce, version: newest_when_first_installed}
The controller process fetches the key and verifies it against
signing_key_sha256, as
files fetched from a web address
describes. On the node, apt_repository first writes an ASCII-armored key
to /etc/apt/keyrings/docker.asc, or a binary key to
/etc/apt/keyrings/docker.gpg. Then apt_repository writes
/etc/apt/sources.list.d/docker.sources. The source file's Signed-By
field names the installed key's path. The apt_package task then refreshes
the package index, because a source changed, and installs docker-ce.
A signing_key_source file on the controller machine, as in the first
example above, takes the place of signing_key_url and signing_key_sha256.
Use a private repository
- apt_repository:
name: nginx-plus
uris: [https://pkgs.nginx.com/plus/debian]
suites: ["{{ .node.distribution.codename }}"]
components: [nginx-plus]
signing_key_source: files/nginx-plus-apt-key.asc
username: "{{ .secrets.nginx_plus_repository_username }}"
password: "{{ .secrets.nginx_plus_repository_password }}"
username and password come together. password must be one whole
reference to a secret, or, inside a role, to a role input declared
secret: true; a password written into the task is rejected at validation. On the
node, MMX writes the login to /etc/apt/auth.conf.d/nginx-plus.conf,
root-owned 0600, with one entry for each of the task's uris, before the
source file. Each entry serves HTTPS only, so apt never sends the login
unencrypted. The login never appears in the source file, which stays
readable by everyone, and a uris value that contains a login is rejected.
The login file's contents are suppressed in previews and results, as for any
task that reads a secret.
Add a Launchpad PPA
A Launchpad PPA is an ordinary source. The PPA's uris value is
https://ppa.launchpadcontent.net/<owner>/<archive>/ubuntu.
The PPA's suite is the node's release codename, and the component is main.
The PPA's key is exported once into the project.
- apt_repository:
name: example-ppa
uris: [https://ppa.launchpadcontent.net/example/tools/ubuntu]
suites: ["{{ .node.distribution.codename }}"]
components: [main]
signing_key_source: files/example-ppa-key.asc
Remove a repository
- apt_repository:
name: docker
state: absent
state: absent accepts only name. It removes the source file, then the
key (docker.asc or docker.gpg), then the login file if there is one.
Packages installed from the source stay. Other files under sources.list.d,
including an older .list file for the same repository, are left alone;
remove them with file.state: absent.
How it works
The key comes from exactly one of signing_key_source or signing_key_url.
A key from signing_key_source is a file in the project, found the way
file.source finds one. An ASCII-armored key is written as <name>.asc and a binary key as
<name>.gpg; MMX does not interpret the key further, and apt verifies
signatures with it. Both files are root-owned 0644, and /etc/apt/keyrings
is created 0755 when missing. The key is installed before the source that
names it.
The files use the ordinary atomic file installer, so matching files are
unchanged, and a dryrun previews them; the result shows the source file's
change, or the key's when only the key changes. A change marks the node
job's package index stale, as a changed file under /etc/apt/ does; the
next installation, version change, or upgrade in that node job refreshes it
first. The task does not refresh the index itself.
Errors and what they mean
- The node uses another package manager. The task fails and names the
module to use instead: on a dnf node,
dnf_repository. - A source that apt cannot use fails the next index refresh, in the package task that follows, and apt's message names the source.
- A
passwordwritten into the task instead of a reference to a secret is rejected at validation. - A
urisvalue that contains a login is rejected. Give the login inusernameandpassword.
Tested on
Distributions: Debian 12 and 13, Ubuntu 24.04 and 26.04.
The suite server_resources.py covers package sources and runs on Debian 12 and 13 and Ubuntu 24.04 and 26.04 for apt_repository.
Why it works this way
- Prefer
signing_key_source. A key is a small file, committing it to the project is done once, and a run then does not depend on the vendor's web address. - MMX does not look keys up on a keyserver during a run.
apt_keyand keys from a keyserver are deprecated upstream, and a keyserver is a third service inside the run;apt_repositoryuses a key file andSigned-By. - No
ppa:shorthand. A PPA is an ordinary source with the archive's key committed to the project. - No unsigned repository. When an unsigned repository is truly needed,
a deb822 file with
Trusted: yesis a plainfiletask. - No client certificate input. A
fileunder/etc/apt/apt.conf.d/that names the certificate and key, and twofiletasks for those, give a repository a client certificate. - The login lives in its own root-only file. The source file stays readable by everyone and never holds the login.
This page is docs/reference/modules/apt_repository.md in the MMX repository.