> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/artifact-registry/3.0/security-and-compliance/signing-keys/setup-signing.md).

# Set up signing keys

Set up GPG or RSA signing keys for your Debian, Alpine, or Wolfi registry, attach them, and configure clients to trust signed packages.

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, go 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

{% tabs %}
{% tab title="Interactive Guide" %}
{% embed url="<https://app.arcade.software/share/TSXifYnNe6qHkkM9XczW>" %}
Generate a New Signing Key for Your Artifact Registry
{% endembed %}
{% endtab %}

{% tab title="Step-by-Step" %}
To generate a signing key:

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**.
   {% endtab %}
   {% endtabs %}

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

{% hint style="warning" %}
**Key expiration**

When a key expires, Harness automatically sets it to Inactive and signing is disabled. You can still upload packages; new metadata is unsigned. To configure alerts, go to [Expiration notifications](https://developer.harness.io/artifact-registry/3.0/security-and-compliance/signing-keys.md#expiration-notifications).
{% endhint %}

### 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.

{% tabs %}
{% tab title="Interactive Guide" %}
{% embed url="<https://app.arcade.software/share/9tHY3xHNFWY0s6rf7ljJ>" %}
Import a Signing Key in Harness
{% endembed %}
{% endtab %}

{% tab title="Step-by-Step" %}
To import a signing key:

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**.
   {% endtab %}
   {% endtabs %}

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.

{% tabs %}
{% tab title="Interactive Guide" %}
{% embed url="<https://app.arcade.software/share/lqXY0iNzUoSVmVzOBHKO>" %}
Attach the signing key from the registry configuration
{% endembed %}
{% endtab %}

{% tab title="Step-by-Step" %}
To attach a signing key to a registry:

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. Set the **Signing enabled** toggle to ON.
6. Select your signing key from the dropdown.
7. Select **Update**.
   {% endtab %}
   {% endtabs %}

{% hint style="info" %}
**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).
{% endhint %}

{% hint style="warning" %}
**One Signing Key per registry**

Each registry supports one Signing Key at a time. Attaching a new key replaces any existing key. Clients that trust only the old public key observe verification errors until they trust the new key.
{% endhint %}

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:

**Generate identity token**

An identity token serves as the password for accessing packages. Select **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:

```bash
curl -fsSL 'https://app.harness.io/har/api/v3/signing-keys/<KEY_ID>/public-key?account_identifier=<ACCOUNT_ID>&routingId=<ACCOUNT_ID>' \
-o /tmp/harness-signing-key.asc
```

2. Convert the key to GPG keyring format:

```bash
gpg --dearmor < /tmp/harness-signing-key.asc | sudo tee /usr/share/keyrings/harness-<REGISTRY_NAME>-archive-keyring.gpg > /dev/null
```

**Configure APT repository**

Add the Debian repository to your APT sources:

1. Add the repository to APT sources:

```bash
echo "deb [signed-by=/usr/share/keyrings/harness-<REGISTRY_NAME>-archive-keyring.gpg] https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/debian <DISTRIBUTION> <COMPONENT>" | sudo tee /etc/apt/sources.list.d/harness.list
```

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

2. Create or edit the auth config file:

```bash
sudo vi /etc/apt/auth.conf.d/harness-<REGISTRY_NAME>.conf
```

3. Add the following content:

```
machine pkg.harness.io
login <USERNAME>
password <TOKEN>
```

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

4. Update the APT cache:

```bash
sudo apt-get update
```

**Install or download a Debian package**

```bash
sudo apt-get install <ARTIFACT_NAME>=<VERSION>
```

### Alpine and Wolfi registries (apk)

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

**Generate identity token**

An identity token serves as the password for authenticating with the registry. Select **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:

```bash
curl -fsSL 'https://app.harness.io/har/api/v3/signing-keys/<KEY_ID>/public-key?account_identifier=<ACCOUNT_ID>&routingId=<ACCOUNT_ID>' \
  -o /tmp/harness-signing-key.pub
```

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

```bash
sudo cp /tmp/harness-signing-key.pub /etc/apk/keys/<KEY_ID>.rsa.pub
```

**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`:

{% tabs %}
{% tab title="Alpine" %}

```bash
sudo sh -c "echo 'https://<USERNAME>:<TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/alpine/<BRANCH>/<REPOSITORY>' >> /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**
  {% endtab %}

{% tab title="Wolfi" %}

```bash
sudo sh -c "echo 'https://<USERNAME>:<TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/wolfi' >> /etc/apk/repositories"
```

Replace `<USERNAME>` and `<TOKEN>` with your Harness credentials (use the identity token as `<TOKEN>`).
{% endtab %}
{% endtabs %}

2. Refresh the index:

```bash
apk update
```

**Install a package**

```bash
apk add <ARTIFACT_NAME>=<VERSION>
```

***

## 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)

```bash
apk update
apk add <ARTIFACT_NAME>=<VERSION>
```

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

***

## Troubleshooting

<details>

<summary>NO_PUBKEY error when running apt-get update (Debian)</summary>

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:

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

```bash
curl -I 'https://app.harness.io/har/api/v3/signing-keys/<KEY_ID>/public-key?account_identifier=<ACCOUNT_ID>&routingId=<ACCOUNT_ID>'
```

2. Re-fetch and trust the key.
3. Run `sudo apt-get update`.

</details>

<details>

<summary>BADSIG error when verifying Debian repository signatures</summary>

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:

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:

```bash
sudo rm /usr/share/keyrings/harness-<REGISTRY_NAME>-archive-keyring.gpg
curl -fsSL 'https://app.harness.io/har/api/v3/signing-keys/<KEY_ID>/public-key?account_identifier=<ACCOUNT_ID>&routingId=<ACCOUNT_ID>' \
-o /tmp/harness-signing-key.asc
gpg --dearmor < /tmp/harness-signing-key.asc | sudo tee /usr/share/keyrings/harness-<REGISTRY_NAME>-archive-keyring.gpg > /dev/null
sudo apt-get update
```

</details>

<details>

<summary>UNTRUSTED signature error when using apk (Alpine or Wolfi)</summary>

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:

1. Verify the public key file exists:

```bash
ls -l /etc/apk/keys/<KEY_ID>.rsa.pub
```

2. Re-download the public key from **Setup Client** and copy it to `/etc/apk/keys/<KEY_ID>.rsa.pub`.
3. Run `apk update`.

</details>

<details>

<summary>401 Unauthorized when accessing the registry</summary>

Missing or incorrect authentication credentials cause this error.

To resolve this error:

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.

</details>

<details>

<summary>404 Not Found when fetching the public key</summary>

No signing key is attached to the registry.

To resolve this error:

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](#step-2-attach-key-to-registry).

</details>

<details>

<summary>Cannot attach a signing key to a registry</summary>

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

</details>

***

## Next steps

* [Manage signing keys](https://developer.harness.io/artifact-registry/3.0/security-and-compliance/signing-keys/manage-signing-keys.md): View, detach, and delete keys.
* [Configure expiration notifications](https://developer.harness.io/artifact-registry/3.0/security-and-compliance/signing-keys.md#expiration-notifications): Set up expiration alerts.

{% @harness-feedback/feedback %}
