> 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/setup/generic.md).

# Generic

Generic - store and retrieve files in Harness Artifacts

Use a **Generic** registry to store and retrieve raw files of any type, such as archives, binaries, scripts, and configuration files, using identity-token-authenticated `curl` requests.

## What you will learn from this topic

By the end of this guide, you will know how to:

* Create a registry in Harness Artifacts.
* Publish a package to the registry.
* Install the package from the registry, and confirm that it works.

## Before you begin

* Install `curl` on your local machine. Most macOS and Linux systems include `curl` by default.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Generic Registry

To create a Generic Registry:

1. In Artifact Registry, select **Registries**.
2. Select **+ Create Registry**.
3. Specify the **Registry name**.

{% hint style="info" %}
**Registry name criteria**

The registry name must start with a letter, can only contain lowercase alphanumerics, `_`, `.`, and `-`, and must be unique to your Harness account.
{% endhint %}

4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Generic** as the **Registry type**.
7. Click **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch files from an external remote registry when they are not available locally. A Generic upstream proxy has no public default source - you supply the remote registry URL yourself.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry**, then choose **Upstream Proxy**.
3. Specify the **Registry name**.
4. Optionally, add a **Description**.
5. Choose visibility between **Public** and **Private**. The default is *Private*.
6. Select **Generic** as the **Registry type**.
7. Select the **Source**: **Custom** (by Default), then specify the **Remote registry URL**, for example `https://artifacts.example.com/generic-repo/`.
8. Select the **Authentication method**.
   * **Username and password**: Specify the username and password. Use an existing secret, or create a new secret by specifying the **Name** and entering the **Secret text**.
   * **Anonymous**: No credentials required.
9. Select **Create** to finalize.

### Configure the upstream proxy in your registry

To configure the upstream proxy in your registry:

1. In Artifact Registry, select an existing Generic artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Select **+ Add upstream proxy**.
5. Select the required proxy from the list.
6. Click **Apply**.
7. Select **Update** to finalize.

{% hint style="info" %}
**Upstream proxy caching**

If a file is not found in your Harness registry, the upstream proxy fetches it from the remote registry URL and caches it.
{% endhint %}

## Generic client setup

In your Generic Artifact, select the registry, and then select **Setup Client**. The dialog gives you an identity token, then the `curl` commands to upload, download, inspect, and delete files.

### Generate an identity token

An identity token serves as the password for uploading and downloading files.

1. In your Generic Artifact, select **Setup Client**.
2. Select **Generate Token**.
3. Select an **Expiration** for the token:
   * **30 Days**
   * **90 Days**
   * **180 Days**
   * **Custom**
4. Copy the token. Use the token in place of `<API_KEY>` in the following steps.

{% hint style="info" %}
**Token expiration**

The identity token stops working after the expiration you select. Generate a new token and update your `curl` commands before the current token expires.
{% endhint %}

### Configure the client

Generic has no client config file or SDK, every operation is a direct `curl` request authenticated with the `x-api-key` header. Each command supports both nested paths (for example, `config/prod/settings.json`) and flat paths (for example, `settings.json`) in place of `<NESTED_FILE_PATH>`.

{% hint style="info" %}
**Correct URL path**

The current Generic file endpoint uses `/files/` in the path, and the deprecated package-level endpoint uses `/generic/`. Do not use `/tools/generic/` or `/tools/files/`; those are different, unrelated endpoints.
{% endhint %}

**1. Publish a file**

Upload a file to a specific path within the package:

```bash
curl -XPUT 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/<ARTIFACT_NAME>/<VERSION>/<NESTED_FILE_PATH>' \
--header 'x-api-key: <API_KEY>' -T '<FILE_PATH>'
```

**2. Use the file**

To download the file, use the path you uploaded it to:

```bash
curl --location 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/<ARTIFACT_NAME>/<VERSION>/<NESTED_FILE_PATH>' \
--header 'x-api-key: <API_KEY>' -J -O
```

**3. Inspect file metadata**

Retrieve metadata for a file without downloading it, using a `HEAD` request:

```bash
curl --location --head 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/<ARTIFACT_NAME>/<VERSION>/<NESTED_FILE_PATH>' \
--header 'x-api-key: <API_KEY>'
```

**4. Delete a file**

Remove a file from a specific path within the package:

```bash
curl --location --request DELETE 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/<ARTIFACT_NAME>/<VERSION>/<NESTED_FILE_PATH>' \
--header 'x-api-key: <API_KEY>'
```

{% hint style="info" %}
**Nested and flat paths**

File operations support both nested paths (for example, `config/prod/settings.json`) and flat paths (for example, `settings.json`), giving you flexibility in how you organize your files.
{% endhint %}

{% hint style="warning" %}
**Deprecated package-level endpoints**

An older `/generic/<ARTIFACT_NAME>/<VERSION>` endpoint uploads and downloads a file at the package level and does not support nested paths. It remains available, but Harness recommends the file-path endpoints in this guide for new integrations.

Upload (deprecated):

```bash
curl --location --request PUT 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/generic/<ARTIFACT_NAME>/<VERSION>' \
--form 'filename="<FILENAME>"' \
--form 'file=@"<FILE_PATH>"' \
--form 'description="<DESC>"' \
--header 'x-api-key: <API_KEY>'
```

Download (deprecated):

```bash
curl --location 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/generic/<ARTIFACT_NAME>/<VERSION>?filename=<FILENAME>' \
--header 'x-api-key: <API_KEY>' -J -O
```

{% endhint %}

## Setup verification

Confirm that your registry serves the file you published. To verify your setup:

1. In a new directory with no previously downloaded copy of the file, run the download command against the path you published to.
2. Confirm that the downloaded file matches the one you uploaded, and that `curl` reported the registry address shown in **Setup Client**.
3. In Harness, open your registry and confirm that the artifact name and version appear in the package list.

If a step fails, go to [Troubleshooting](#troubleshooting) to resolve common authentication and resolution issues before you retry.

## Pipeline automation (optional)

Publishing from a pipeline gives you a repeatable release process. Run the publish step when you create a version tag, so each release maps to one version in the registry.

The following Run step shows the shape of a publish step. Store the identity token as a Harness secret, and do not write it into the pipeline YAML.

```yaml
- step:
    type: Run
    name: Publish package
    identifier: publish_package
    spec:
      shell: Sh
      envVariables:
        PACKAGE_VERSION: <+codebase.tag>
      command: |
        curl -XPUT 'https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/<ARTIFACT_NAME>/'"$PACKAGE_VERSION"'/<NESTED_FILE_PATH>' \
        --header 'x-api-key: <API_KEY>' -T '<FILE_PATH>'
```

## Troubleshooting

<details>

<summary>A file upload returns `401` or `403`</summary>

Check that the `x-api-key` header carries the identity token you generated in **Setup Client**, and that the token has not expired or been revoked. Generate a new token and update your `curl` command if needed.

</details>

<details>

<summary>A file upload to the same artifact and version returns `409 Conflict`</summary>

Artifact versions are immutable after publish. Upload under a new version, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>A download or `HEAD` request returns `404 Not Found`</summary>

Check that `<ARTIFACT_NAME>`, `<VERSION>`, and `<NESTED_FILE_PATH>` match the values you used to upload the file exactly, including case and any nested folder segments. Also check that `<REGISTRY_NAME>` and `<ACCOUNT_ID>` in the URL are correct.

</details>

<details>

<summary>Setup Client does not show upload commands for an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Setup Client** omits upload instructions there. Publish files to a standard, non-proxy Generic registry instead, or let the upstream proxy cache files on first download.

</details>

<details>

<summary>A file upload returns `413 Request Entity Too Large`</summary>

The maximum file size for a single upload to a Generic registry is 5 TiB. This limit cannot be changed from the Harness UI. If you receive a `413` error for a file smaller than 5 TiB, contact Harness Support.

</details>

<details>

<summary>A folder cannot be uploaded as a single artifact</summary>

A Generic registry stores individual files, not folders. Archive the folder and upload the archive as one file, or upload each file under the same artifact and version with its own nested file path. File paths accept only letters, digits, and the characters `.`, `_`, `~`, `@`, and `-`; spaces are rejected.

</details>

## Next steps

* To add a pipeline that publishes a new version for every release tag, go to [Harness CI](https://developer.harness.io/artifact-registry/3.0/platform-integrations/harness-ci.md).
* To control who can publish and consume packages in your registry, go to [RBAC and permissions](https://developer.harness.io/artifact-registry/3.0/reference/rbac-and-permissions.md).
* To set retention and lifecycle rules for old versions, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}
