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

# Conda

Conda - host Conda packages in Harness Artifacts

Use a **Conda** registry to host private Conda packages for installation with the Conda CLI.

## 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 the Conda CLI (`conda`) on your local machine.
* Install the Harness CLI (`hc`). You use it to publish packages to your registry.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Conda Registry

To create a Conda 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*.

{% hint style="info" %}
**Private registries**

If you select **Private**, only users with permission on the registry can pull packages from it.
{% endhint %}

6. Select **Conda** 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 Conda packages from external sources, such as Bioconda, when they are not available locally. The default source is **Bioconda**.

### 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 **Conda** as the **Registry type**.
7. Select the **Source**: **Bioconda** or **Custom**.
   * If you select **Custom**, 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. Click **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 Conda 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 Conda package is not found in your Harness registry, the upstream proxy fetches it from the configured source, such as Bioconda, and caches it for future requests.
{% endhint %}

## Conda client setup

In your Conda Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token and the commands you need to publish and install packages with the conda CLI.

### Generate an identity token

An identity token serves as the password for authenticating with the registry.

1. In your Conda Artifact Registry, 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. You use it in the following steps in place of `<IDENTITY_TOKEN>`.

{% 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

In the code samples, replace the values in angle brackets with your own values.

**1. Build the package**

Build a Conda package from your project's recipe directory:

```bash
conda build .
```

**2. Publish the package**

Run the following command from your project's root directory to push the package to your registry:

```bash
hc artifact push conda <REGISTRY_NAME> <FILE_PATH> --pkg-url pkg.harness.io
```

**3. Install the package**

Install the package with the conda CLI, specifying your registry channel and identity token:

```bash
conda install --channel https://<HARNESS_USERNAME>:<IDENTITY_TOKEN>@pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/conda <ARTIFACT_NAME>=<VERSION>
```

## Setup verification

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

1. In a new directory with no cached Conda indices or packages, run the `conda install` command shown in **Configure the client**, using the artifact name and version you published.
2. Confirm that conda downloaded the package from your Harness registry address, which is shown in **Setup Client**.
3. In Harness, open your registry and confirm that the package 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. Reference `$PACKAGE_VERSION` in your recipe's `meta.yaml` to pin each build to the tag. 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: |
        conda build . --output-folder ./dist
        hc artifact push conda <REGISTRY_NAME> ./dist/<PACKAGE_FILE> --pkg-url pkg.harness.io
```

## Troubleshooting

<details>

<summary>`conda install` fails with `401` or `403` against a Conda registry</summary>

Check that the registry address in your install command matches the one shown in **Setup Client**, and that the identity token is the one you generated there. If the token has expired or was revoked, generate a new one and update your command.

</details>

<details>

<summary>`hc artifact push conda` returns a `409 Conflict`</summary>

Package versions are immutable after publish. Increment the version in your recipe's `meta.yaml`, rebuild the package, and publish the new version.

</details>

<details>

<summary>`conda install` fails with `PackagesNotFoundError`</summary>

Check that the package name and version match the values you used when you published the package. Also, check that the registry name and account ID in your channel URL are correct.

</details>

<details>

<summary>Setup Client omits the publish command for an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Setup Client** only shows install instructions. To publish packages, create a standard registry and push to it directly, or configure the upstream proxy as a source for a registry you can both publish to and pull from.

</details>

<details>

<summary>`conda install` resolves a stale version after a new publish</summary>

Clear the local channel index cache, then retry the install:

```bash
conda clean --index-cache
```

</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 %}
