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

# Conan

Conan - host C/C++ packages in Harness Artifacts

Use a **Conan** registry to host Conan packages for C and C++ projects, including recipe revisions and prebuilt binaries, for consumption with the Conan 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 Conan CLI (`conan`) on your local machine.
* Make sure you have access to a Harness account with permission to create registries and connectors.

## Create a Conan Registry

To create a Conan 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 **Conan** as the **Registry type**.
7. Select **Save**.
8. Select **Create** to finalize.

## Configure an upstream proxy (optional)

An upstream proxy allows your registry to fetch Conan packages from external sources, such as Conan Center, when they are not available locally. The default upstream is Conan Center.

### 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 **Conan** as the **Registry type**.
7. Select the **Source**: **Conan Center** or **Custom**.
   * If you select **Custom**, specify the **Remote registry URL** (for example, `https://center2.conan.io`).
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. This works for public Conan sources such as Conan Center.
9. Optionally, configure the **Metadata configuration**:
   * **Metadata Cache TTL (seconds)**: How long the registry keeps cached package metadata from the upstream source before it fetches that metadata again.
   * **Negative Cache TTL (seconds)**: How long the registry caches a not-found response before it repeats the upstream lookup for a package it already failed to find.

{% hint style="info" %}
**Metadata configuration defaults**

Metadata Cache TTL and Negative Cache TTL each accept a value from 0 to 604,800 seconds (7 days). The default for both is 600 seconds (10 minutes), and a value of 0 uses that default. Neither setting removes cached packages. Go to [Configure metadata cache TTL](https://developer.harness.io/artifact-registry/3.0/registries/create-an-upstream-proxy.md#configure-metadata-cache-ttl) for the full field reference.
{% endhint %}

10. 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 Conan Artifact.
2. Navigate to the **Configuration** tab.
3. Click **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 package is not found in your Harness registry, the upstream proxy fetches it from Conan Center or your configured source, and caches it.
{% endhint %}

## Conan client setup

In your Conan Artifact, select the registry, then select **Setup Client**. The dialog gives you an identity token, then setup instructions for adding the registry as a Conan remote.

### Generate an identity token

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

1. In your Conan 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

Replace the values in angle brackets with your own values in the following steps.

**1. Configure the Conan remote**

Add the registry as a Conan remote:

```bash
conan remote add <REMOTE_NAME> https://pkg.harness.io/pkg/<ACCOUNT_ID>/<REGISTRY_NAME>/conan
```

Authenticate with your identity token:

```bash
conan remote login <REMOTE_NAME> <YOUR_EMAIL> -p <IDENTITY_TOKEN>
```

**2. Publish the package**

Build the package locally:

```bash
conan create .
```

Upload it to the registry:

```bash
conan upload <ARTIFACT_NAME>/<VERSION> -r <REMOTE_NAME> --confirm
```

**3. Install the package**

Install the package from the registry:

```bash
conan install --requires=<ARTIFACT_NAME>/<VERSION> -r <REMOTE_NAME>
```

## Setup verification

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

1. In a local Conan cache with no previously downloaded recipe or package matching the same name and version, use the Conan CLI to install the package you published.
2. Confirm that the client 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.

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: |
        conan create . --version="$PACKAGE_VERSION"
        conan upload <ARTIFACT_NAME>/"$PACKAGE_VERSION" -r <REMOTE_NAME> --confirm
```

## Troubleshooting

<details>

<summary>`conan remote login` fails with `401` or `403`</summary>

Check that the registry address in your `conan remote add` 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 remote configuration.

</details>

<details>

<summary>`conan upload` returns `409 Conflict`</summary>

The recipe or package revision already exists in the registry. Create a new revision by changing the recipe or source, or delete the existing version only if your registry retention and lifecycle policies allow it.

</details>

<details>

<summary>`conan install` cannot resolve `/`</summary>

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

</details>

<details>

<summary>Setup Client omits the `conan upload` command for an upstream proxy registry</summary>

An upstream proxy registry is pull-only, so **Setup Client** gives you only the `conan remote add` and `conan install` steps. Publish to a private Conan registry instead, or cache public packages through the upstream proxy.

</details>

<details>

<summary>Conan cache still resolves an old revision after a new upload</summary>

Clear the local Conan cache entry for that reference, or pass `--update` to `conan install` to force Conan to check the registry for a newer revision.

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