Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Configuring the APT package manager

Written by
Updated at August 4, 2026
View in Markdown

This guide describes how to configure the APT package manager (Advanced Package Tool) to work with the Debian registry in Yandex Cloud Registry.

Preparing a GPG key

A GPG key is required for a registry with signed metadata. The signature allows clients to verify the authenticity of packages using the GPG key.

  1. Generate a GPG key using the GnuPG utility:

    gpg --full-generate-key

    When prompting for passphrase, leave this field empty.

  2. Find the ID of the created GPG key:

    gpg --list-secret-keys --keyid-format=long

    Result:

    /home/user/.gnupg/secring.gpg
------------------------------
sec   4096R/<GPG_key_ID> 2024-01-01 [expires: 2026-01-01]
uid                          User Name <user@example.com>
ssb   4096R/XXXXXXXXXXXXXXXX 2024-01-01

  3. Export the secret part of the GPG key:

    gpg --armor --export-secret-keys <GPG_key_ID>

  4. Save the secret part of the GPG key in a Yandex Lockbox secret under the gpg_secret_key_value key:

    yc lockbox secret create \
  --name <secret_name> \
  --payload "[{'key': 'gpg_secret_key_value', 'text_value': '$(gpg --armor --export-secret-keys <GPG_key_ID>)'}]"

  5. Grant access to the contents of the secret to the Cloud Registry service agent by assigning it the lockbox.payloadViewer role for this secret:

    yc lockbox secret add-access-binding \
  --id <secret_ID> \
  --role lockbox.payloadViewer \
  --agent cloud-registry:control-plane \
  --cloud-id <cloud_ID>

  6. Save the public part of the GPG key; the registry users will need it:

    gpg --armor --export <GPG_key_ID> > public-key.asc

Configuring APT

To configure APT, add:

  • Registry to the APT sources list.
  • Authentication data to the /etc/apt/auth.conf file.

Your method of adding a registry to the APT sources list will vary depending on registry format and source type.

Adding a registry to the APT sources list

Local registry

  1. Copy the public GPG key to the APT trusted keys directory:

    cp /path/to/public-key.asc /usr/share/keyrings/ycr-pub.asc

    Where /path/to/public-key.asc is the path to the file with the public GPG key.

  2. Add the registry to the APT sources list:

    echo "deb [signed-by=/usr/share/keyrings/ycr-pub.asc] https://registry.yandexcloud.net/debian/<registry_ID> <distribution> <component>" \
  >> /etc/apt/sources.list

Add the registry with the trusted=yes parameter:

echo "deb [trusted=yes] https://registry.yandexcloud.net/debian/<registry_ID> <distribution> <component>" \
  >> /etc/apt/sources.list

Remote registry

  1. Install the distribution public key package:

    • For Debian:

      sudo apt install debian-archive-keyring

      The key will be available at /usr/share/keyrings/debian-archive-keyring.gpg.

    • For Ubuntu:

      sudo apt install ubuntu-keyring

      The key will be available at /usr/share/keyrings/ubuntu-archive-keyring.gpg.

  2. Add the registry to the APT sources list:

    echo "deb [signed-by=<path_to_key>] https://registry.yandexcloud.net/debian/<registry_ID> <distribution> <component>" \
  >> /etc/apt/sources.list

    Where:

    • <path_to_key>: Path to the distribution key file, for example /usr/share/keyrings/debian-archive-keyring.gpg or /usr/share/keyrings/ubuntu-archive-keyring.gpg.
    • <registry_ID>: Registry ID.
    • <distribution>: Distribution, e.g., bookworm, bullseye, or focal.
    • <component>: Repository component, e.g., main.

  1. Save a GPG key to the trusted keys directory:

    cp /path/to/upstream-public-key.asc /usr/share/keyrings/upstream-pub.asc

    Where /path/to/upstream-public-key.asc is the path to the public key file of the source repository (upstream).

  2. Add the registry to the APT sources list:

    echo "deb [signed-by=/usr/share/keyrings/upstream-pub.asc] https://registry.yandexcloud.net/debian/<registry_ID> <distribution> <component>" \
  >> /etc/apt/sources.list

Specify the trusted=yes parameter so that APT accepts packages without authentication:

echo "deb [trusted=yes] https://registry.yandexcloud.net/debian/<registry_ID> <distribution> <component>" \
  >> /etc/apt/sources.list

Adding authentication credentials

Warning

The APT package manager does not inject environment variables into configuration files. To protect your credentials, restrict access to /etc/apt/auth.conf at the OS level.

  1. Select the authentication method:

    Get an IAM token for the Yandex account or service account you are going to use for authentication.

    Note

    The IAM token's lifetime is limited to 12 hours.

    Create an API key for the service account you are going to use for authentication.

    Note

    The API key maximum lifetime is set manually when you create the key.

  2. Add authentication data to the /etc/apt/auth.conf file:

    machine https://registry.yandexcloud.net/debian/<registry_ID>
login iam
password <IAM_token>

    machine https://registry.yandexcloud.net/debian/<registry_ID>
login api_key
password <API_key>

Useful links

Previous
Pushing a Go module from the registry
Next
Pushing a Debian package to a registry