For the complete documentation index, see llms.txt. This page is also available as Markdown.

Set up signing keys

Set up GPG or RSA signing keys for your Debian, Alpine, or Wolfi registry.

Follow this guide to set up repository signing end to end. Create a signing key, attach it to your registry, and configure clients to trust only signed packages.


Step 1: Create a signing key

To create a signing key, navigate to Registries Settings > Signing Keys, and then select Create Signing Key.

Choose how to create your key: generate a new key pair in Harness, or import a key you already use.

Generate a key

spinner
Generate a New Signing Key for Your Artifact Registry

To generate a signing key, perform the following steps:

  1. Select Generated as the key source.

  2. Specify the Key Name. The name must be unique per scope (account, organization, or project).

  3. Choose Type based on your registry:

    • GPG for Debian registries

    • RSA for Alpine and Wolfi registries

  4. Select Algorithm:

    • RSA: Maximum compatibility. Required when Type is RSA.

    • Ed25519: Better performance on newer systems. Available only when Type is GPG.

  5. Set Expiration (optional):

    • Never: Key remains valid indefinitely

    • Custom period: Specify validity (1 year, 2 years, 5 years)

  6. Click Generate.

Harness creates the key pair and stores the private key securely. You can attach it to registries immediately or later.

Import a key

To import a signing key, store the private key content in a Harness Secret Manager secret. You can create a new secret or use an existing one.

spinner
Import a Signing Key in Harness

To import a signing key, perform the following steps:

  1. Select Imported as the key source.

  2. Specify the Key Name. The name must be unique per scope (account, organization, or project).

  3. Choose Type (GPG or RSA).

  4. Provide the Private Key:

    • Option 1: Select an existing secret from your Harness account.

    • Option 2: Create a new secret. Enter a Name, paste the complete Secret Text (entire key including headers), and optionally add Metadata (description, tags).

  5. If the key is protected by a passphrase, provide the Passphrase:

    • Option 1: Select an existing passphrase secret from your Harness account.

    • Option 2: Create a new secret. Enter a Name, enter the passphrase as Secret Text, optionally add Metadata, and then click Save.

  6. Click Import.

Harness validates the key format and algorithm before storing it securely.


Step 2: Attach key to registry

Attach the signing key from the registry configuration so Harness can sign repository metadata on upload.

spinner
Attach the signing key from the registry configuration

To attach a signing key to a registry, perform the following steps:

  1. In the Artifact Registry module, select Registries.

  2. Select your registry.

  3. Select the Configuration tab.

  4. In the Signing keys section, select Edit.

  5. Toggle Signing enabled on.

  6. Select your signing key from the dropdown.

  7. Click Update.

Virtual registries only

Attach Signing Keys only to virtual registries. If you do not see the signing option, verify the registry is virtual (not upstream).

After you attach a key, Harness signs repository metadata on every package upload. Signing is optional; without an attached key, metadata remains unsigned.


Step 3: Configure clients

Clients must trust your public key before installing packages. Open your registry and select Setup Client to get commands pre-filled with the following:

  • Account ID

  • Registry name

  • Signing key URL

  • Credentials

Debian registries (apt)

To install Debian packages from the registry, perform the following steps:

Generate identity token

An identity token serves as the password for accessing packages. Click Setup Client to generate an identity token.

Configure repository signing key

Download and configure the GPG signing key for package verification.

  1. Download the public signing key:

  1. Convert the key to GPG keyring format:

Configure APT repository

Add the Debian repository to your APT sources.

  1. Add the repository to APT sources:

Replace <DISTRIBUTION> (for example, stable, bookworm, jammy) and <COMPONENT> (for example, main, contrib).

  1. Create or edit the auth config file:

  1. Add the following content:

Use the identity token from Generate identity token as <TOKEN>.

  1. Update the APT cache:

Install or download a Debian package

Alpine and Wolfi registries (apk)

Self-published indexes are signed with RSA256. To install packages from the registry on each client machine, perform the following steps:

Generate identity token

An identity token serves as the password for authenticating with the registry. Click Setup Client to generate an identity token.

Configure repository signing key

Download and install the RSA signing key for package verification.

  1. Download the public signing key:

  1. Install the key to the apk trusted keys directory:

Configure apk repository

Point apk at the registry. Indexes are signed with RSA256. Use the Alpine URL with branch and repository segments, or the Wolfi URL without those segments.

  1. Add the registry to /etc/apk/repositories:

Replace the following placeholders:

  • <USERNAME>, <TOKEN>: Your Harness credentials (use the identity token as <TOKEN>)

  • <BRANCH>, <REPOSITORY>: The Alpine branch and repository path from Setup Client

Replace <USERNAME> and <TOKEN> with your Harness credentials (use the identity token as <TOKEN>).

  1. Refresh the index:

Install a package


Verify setup

Confirm that the client trusts the signing key by installing a package from the registry.

Test Debian (apt)

After sudo apt-get update and sudo apt-get install, success means there are no signature verification errors and the package installs normally.

Test Alpine and Wolfi (apk)

Success means there are no UNTRUSTED signature errors and the package installs normally.


Troubleshooting

NO_PUBKEY error when running apt-get update (Debian)

The error The following signatures couldn't be verified because the public key is not available: NO_PUBKEY means the client does not trust the registry signing key.

To resolve the error, perform the following steps:

  1. Verify the public key URL from Setup Client is correct:

  1. Re-fetch and trust the key.

  2. Run sudo apt-get update.

BADSIG error when verifying Debian repository signatures

The error The following signatures were invalid: BADSIG usually means the key was replaced, or the key status is Inactive or Revoked.

To resolve the error, perform the following steps:

  1. Check the key status in Registries Settings > Signing Keys.

  2. If the key is Inactive, change the status to Active.

  3. If the key was replaced, remove the old keyring and fetch the new key:

UNTRUSTED signature error when using apk (Alpine or Wolfi)

The error UNTRUSTED signature means the client does not trust the registry signing key, or the public key file is missing or incorrect.

To resolve the error, perform the following steps:

  1. Verify the public key file exists:

  1. Re-download the public key from Setup Client and copy it to /etc/apk/keys/<KEY_ID>.rsa.pub.

  2. Run apk update.

401 Unauthorized when accessing the registry

Missing or incorrect authentication credentials cause this error.

To resolve this error, perform the following steps:

  1. Verify the auth config exists (Debian: /etc/apt/auth.conf.d/, Alpine and Wolfi: credentials embedded in the repository URL).

  2. Generate a new token on the registry Setup Client page.

  3. Update the credentials and retry.

404 Not Found when fetching the public key

No signing key is attached to the registry.

To resolve this error, perform the following steps:

  1. Verify a signing key is attached in the registry Configuration > Signing keys section.

  2. If no key is attached, go to Step 2: Attach key to registry.

Cannot attach a signing key to a registry

Signing keys can only be attached to virtual registries, and the key type must match the registry type.

To resolve this error, check the following:

  • Confirm the target registry is virtual. Upstream registries do not support signing keys.

  • Match the key type to the registry:

    • GPG keys for Debian registries only

    • RSA keys for Alpine and Wolfi registries only


Next steps

Last updated

Was this helpful?