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

Configuring the APT package manager

Written by
Updated at October 30, 2026
View in Markdown

This guide describes how to connect the APT package manager (Advanced Package Tool) to a 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.

  1. Generate a GPG key using GnuPG:

    gpg --full-generate-key

    When prompted for passphrase, leave this field empty.

  2. Retrieve the ID of the GPG key you created:

    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 secret contents 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. Registry users will need this value:

    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 directory with APT trusted keys:

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

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

  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 a registry with trusted=yes:

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

Remote registry

  1. Install the package with the distribution public keys:

    • 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, e.g., /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 for APT to accept unauthenticated packages:

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.

    When creating a key, specify its scope:

    • yc.cloud-registry.artifacts.pull: To pull artifacts from the registry.
    • yc.cloud-registry.artifacts.push: To push artifacts to the registry.

    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

Scope is an API key parameter that restricts the key's use to specific operations in addition to the service account's access permissions. For details, see API keys with scope and validity limits.

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