Managing and Adding APT Repositories

Best practices, references, and helpers for managing custom APT repositories on Debian-derived systems.

The general advice is to put source lists in /etc/apt/sources.list.d/ and keys in /etc/apt/keyrings/, referenced by Signed-By entries. The use of DEB822 Source Format is encouraged, as it simplifies managing repositories manually.

Resources

• Debian Wiki's general instructions on third-party repositories: https://wiki.debian.org/DebianRepository/UseThirdParty
• Repolib's documentation of the DEB822 Source Format: https://repolib.readthedocs.io/en/latest/deb822-format.html
• Man page for APT sources.list: https://manpages.debian.org/unstable/apt/sources.list.5.en.html

Converting list format to DEB822

Given a line in the traditional list format deb [arch=arch1,arch2,... signed-by=/path/to/key] https://repo.url distribution component1 component2 ..., the corresponding DEB822 sources entry becomes:

Enabled: yes
Types: deb
URIs: https://repo.url
Suites: distribution ...
Components: component1 component2 ...
Architectures: arch1 arch2 ...
Signed-By: /path/to/key

Note: the distribution in the traditional entry becomes (one of) the Suites in the DEB822 entry.

Signing Keys

Signing keys should be placed in /etc/apt/keyrings/ and then by referenced by their file path in the Signed-By option in the source list entry.

Alternatively, keys can be ASCII-armored and referenced inline in a DEB822 source list:

Signed-By:
  -----BEGIN PGP PUBLIC KEY BLOCK-----
  .
  mQINBGdCz4IBEACqA2UybPzUDw81EG0nXNUJ4Fk64pRkKqC5FwWUg7dPA4rtdMao
  -----END PGP PUBLIC KEY BLOCK-----

Note that a single dot . must be used to replace the empty line, otherwise the empty line will split the file into multiple entries.

Pinning

Add a .pref file in /etc/apt/preferences.d/ to allow only specified packages to be installed by using pinning.

See "Standard pinning" in the linked Debian Wiki page.

For example, to disable packages from contrib and non-free, but allow installation of libdvd-pkg:

Explanation: Disable packages from debian contrib and non-free components by default
Package: *
Pin: release o=Debian,a=/^(stable|stable-updates|stable-security)$/,l=/^(Debian|Debian-Security)$/,c=/^(contrib|non-free)$/
Pin-Priority: -1

Explanation: Install libdvd-pkg from contrib
Package: libdvd-pkg
Pin: release o=Debian,a=stable,l=Debian,c=contrib
Pin-Priority: 500

Or alternatively Pin: origin repo.url