ansible.builtin.apt_repository module – Add and remove APT repositories

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name apt_repository even without specifying the collections keyword. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.apt_repository for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis
Requirements
Parameters
Attributes
Notes
See Also
Examples
Return Values

Synopsis

Add or remove an APT repositories in Ubuntu and Debian.

Requirements

The below requirements are needed on the host that executes this module.

python-apt (python 2)
python3-apt (python 3)
apt-key or gpg

Parameters

Parameter	Comments
codename string	Override the distribution codename to use for PPA repositories. Should usually only be set when working with a PPA on a non-Ubuntu target (for example, Debian or Mint).
filename string	Sets the name of the source list file in sources.list.d. Defaults to a file name based on the repository source url. The .list extension will be automatically added.
install_python_apt boolean	Whether to automatically try to install the Python apt library or not, if it is not already installed. Without this library, the module does not work. Runs `apt-get install python-apt` for Python 2, and `apt-get install python3-apt` for Python 3. Only works with the system Python 2 or Python 3. If you are using a Python on the remote that is not the system Python, set `install_python_apt=false` and ensure that the Python apt library for your Python version is installed some other way. Choices: `false` `true` ← (default)
mode any	The octal mode for newly created files in sources.list.d. Default is what system uses (probably 0644).
repo string / required	A source string for the repository.
state string	A source string state. Choices: `"absent"` `"present"` ← (default)
update_cache aliases: update-cache boolean	Run the equivalent of `apt-get update` when a change occurs. Cache updates are run after making changes. Choices: `false` `true` ← (default)
update_cache_retries integer added in ansible-base 2.10	Amount of retries if the cache update fails. Also see `update_cache_retry_max_delay`. Default: `5`
update_cache_retry_max_delay integer added in ansible-base 2.10	Use an exponential backoff delay for each retry (see `update_cache_retries`) up to this max delay in seconds. Default: `12`
validate_certs boolean	If `false`, SSL certificates for the target repo will not be validated. This should only be used on personally controlled sites using self-signed certificates. Choices: `false` `true` ← (default)

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.
diff_mode	Support: full	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platform: debian	Target OS/families that can be operated against

Notes

Note

This module supports Debian Squeeze (version 6) as well as its successors and derivatives.

Examples

- name: Add specified repository into sources list
  ansible.builtin.apt_repository:
    repo: deb http://archive.canonical.com/ubuntu hardy partner
    state: present

- name: Add specified repository into sources list using specified filename
  ansible.builtin.apt_repository:
    repo: deb http://dl.google.com/linux/chrome/deb/ stable main
    state: present
    filename: google-chrome

- name: Add source repository into sources list
  ansible.builtin.apt_repository:
    repo: deb-src http://archive.canonical.com/ubuntu hardy partner
    state: present

- name: Remove specified repository from sources list
  ansible.builtin.apt_repository:
    repo: deb http://archive.canonical.com/ubuntu hardy partner
    state: absent

- name: Add nginx stable repository from PPA and install its signing key on Ubuntu target
  ansible.builtin.apt_repository:
    repo: ppa:nginx/stable

- name: Add nginx stable repository from PPA and install its signing key on Debian target
  ansible.builtin.apt_repository:
    repo: 'ppa:nginx/stable'
    codename: trusty

- name: One way to avoid apt_key once it is removed from your distro
  block:
    - name: somerepo |no apt key
      ansible.builtin.get_url:
        url: https://download.example.com/linux/ubuntu/gpg
        dest: /etc/apt/keyrings/somerepo.asc

    - name: somerepo | apt source
      ansible.builtin.apt_repository:
        repo: "deb [arch=amd64 signed-by=/etc/apt/keyrings/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
        state: present

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
repo string	A source string for the repository Returned: always Sample: `"deb https://artifacts.elastic.co/packages/6.x/apt stable main"`
sources_added list / elements=string added in ansible-core 2.15	List of sources added Returned: success, sources were added Sample: `["/etc/apt/sources.list.d/artifacts_elastic_co_packages_6_x_apt.list"]`
sources_removed list / elements=string added in ansible-core 2.15	List of sources removed Returned: success, sources were removed Sample: `["/etc/apt/sources.list.d/artifacts_elastic_co_packages_6_x_apt.list"]`

Authors

Alexander Saltanov (@sashka)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/apt_repository_module.html