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>.sources and /etc/apt/keyrings/<name>.asc, or <name>.gpg for a binary key
  • uris (list of strings; required): omit with absent
  • suites (list of strings; required): omit with absent; a suite ending in / is a flat repository
  • components (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_url
  • signing_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.name
  • signing_key_sha256 (string; optional): the key's SHA-256 in hex; with signing_key_url, exactly one of signing_key_sha256 or dangerously_skip_checksum
  • dangerously_skip_checksum (boolean; default false): true in place of signing_key_sha256: the key is trusted as it arrives
  • username (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 file
  • password (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: true
  • state (present or absent; default present): 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.

  • status
  • change

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 password written into the task instead of a reference to a secret is rejected at validation.
  • A uris value that contains a login is rejected. Give the login in username and password.

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_key and keys from a keyserver are deprecated upstream, and a keyserver is a third service inside the run; apt_repository uses a key file and Signed-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: yes is a plain file task.
  • No client certificate input. A file under /etc/apt/apt.conf.d/ that names the certificate and key, and two file tasks 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.