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

# Raw

Raw - store raw files in Harness Artifacts

{% hint style="info" %}
This feature is in Beta[^1] and requires enablement. [View all early access features.](https://developer.harness.io/release-notes/features.md)

{% @harness-feature-flag-access/request-feature-flag-access module="artifacts" pagePath="artifacts/setup/raw" pageTitle="Raw" featureFlags="%5B%7B%22name%22%3A%22Raw%20registry%22%2C%22key%22%3A%22HAR\_RAW\_PACKAGE%22%2C%22status%22%3A%22BETA%22%2C%22description%22%3A%22Enables%20the%20Raw%20registry%20type%20for%20storing%20and%20retrieving%20files%20of%20any%20type%20by%20path.%22%7D%5D" %}
{% endhint %}

Use a **Raw** registry to store and retrieve files of any type, such as archives, binaries, 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 the working.

## Before you begin

* Install `curl` on your local machine.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Raw registry

To create a Raw 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 **Raw** 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 source when they are not available locally.

### Create upstream proxy

To create an upstream proxy:

1. In Artifact Registry, select **Registries**.
2. Select the drop-down next to **+ Create Registry** and select **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 **Raw** as the **Registry type**.
7. Select **Custom** as the **Source**, then specify the **Remote registry URL**.
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 Raw Artifact.
2. Navigate to the **Configuration** tab.
3. Select **Edit** in the **Upstream proxy** section.
4. Click **+ 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 and caches it.
{% endhint %}

## Raw client setup

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

### Generate an identity token

An identity token serves as the password for file operations.

1. In your Raw Artifact Registry, select **Set Up 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 client configuration before the current token expires.
{% endhint %}

### Configure the client

Raw files have no config file or install step. You address every file directly by its path with `curl`. In the commands that follow, replace the values in angle brackets with your own values.

**1. Upload a file to a specific path**

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

**2. Download a file from a specific path**

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

**3. Get file metadata**

Send a HEAD request to retrieve a file's metadata without downloading it:

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

**4. Delete a file**

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

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

`<FILE_PATH>` supports both nested paths (for example, `config/prod/settings.json`) and flat paths (for example, `settings.json`), so you can organize files using directory structures in the path.
{% endhint %}

{% hint style="info" %}
**URL encoding and hostnames**

Use the exact URL pattern shown in **Set Up Client** for your registry if it differs from the examples in this section, for example a cluster-specific hostname. For a path that contains special characters, copy the command from **Set Up Client**, or URL-encode the path segments yourself.
{% 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 to retrieve the file you uploaded.
2. Confirm that the downloaded file is byte-identical to the file you uploaded, and that the response came from your Harness registry address shown in **Set Up Client**.
3. In Harness, open your registry and confirm that the file appears in the file 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 upload step when you create a release tag, so each release maps to one file path in the registry.

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

```yaml
- step:
    type: Run
    name: Upload file
    identifier: upload_file
    spec:
      shell: Sh
      envVariables:
        FILE_VERSION: <+codebase.tag>
      command: |
        curl -XPUT "https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/files/<FILE_NAME>/$FILE_VERSION/<FILE_NAME>" \
        --header "x-api-key: <API_KEY>" -T "<LOCAL_FILE_PATH>"
```

## Troubleshooting

<details>

<summary>A `curl -XPUT` upload returns `401` or `403` against a Raw registry</summary>

Check that the registry address in your command matches the one shown in **Set Up Client**, and that `<API_KEY>` is the identity token you generated there. If the token expired or was revoked, generate a new one and update your command.

</details>

<details>

<summary>A `curl -XPUT` to an existing file path returns `409 Conflict`</summary>

Files are immutable at a given path after upload. Upload the file to a new path, or delete the existing file first if your registry's retention and lifecycle policies allow it.

</details>

<details>

<summary>A `curl` download returns `404 Not Found` for a file that exists</summary>

Check that `<FILE_PATH>` matches the exact path you uploaded to, including case and any nested directories. A flat path and a nested path with the same filename resolve to different files.

</details>

<details>

<summary>Set Up Client omits upload commands for an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Set Up Client** shows only the download, metadata, and delete commands. To publish new files, upload them to a virtual Raw registry instead, or let the upstream proxy cache files on first download.

</details>

## Next steps

* To add a pipeline that publishes a new file 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 files 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 files, go to [Lifecycle Management overview](https://developer.harness.io/artifact-registry/3.0/lifecycle-management/overview.md).

{% @harness-feedback/feedback %}

[^1]: Off by default. If you want to try it and share feedback, request access and Harness will turn it on for your account. Beta features can change and may not be ready for production use.
