---
url: /en/artifact/conan.md
description: >
  Guide for using the CNB Conan artifact repository to store and distribute
  C/C++ packages, covering remote configuration, authentication, and
  pushing/pulling packages via local CLI and CI pipelines.
---
Conan Artifact Repository is used to store and distribute C/C++ packages.
It supports uploading, managing and installing various C/C++ third-party
libraries and tools.

## Prerequisites

1. [Create Artifact Registry](./intro.md#creating-an-artifact-registry)
2. [Obtain Artifact Registry Address](./intro.md#obtaining-the-artifact-registry-address)
3. [Create Access Token](./intro.md#creating-an-access-token)

## Local Development

### Add a Remote and Login

`<REMOTE_NAME>` is your chosen name for the remote, `<REPO_URL>` is the URL of your repository.

```shell
conan remote add <REMOTE_NAME> <REPO_URL>
conan remote login -p <YOUR_TOKEN> <REMOTE_NAME> cnb
```

### Pull Artifacts

```shell
conan download <PACKAGE_NAME> -r <REMOTE_NAME>
```

### Build and Push Artifacts

```shell
conan create . --user=<USER> --channel=<CHANNEL>
conan upload <PACKAGE_NAME> -r <REMOTE_NAME>
```

## Cloud Native Build

Cloud Native Build supports two methods for token usage,
see \[Using Tokens in Cloud Native Build and Workspaces]
(./intro.md#using-tokens-in-cloud-native-build-and-cloud-native-development).

### Configure Credentials, Pull and Push

The following example uses `CNB_TOKEN` (recommended) and combines credential
configuration, pull, and push into a single pipeline. To use secret repository
files, see \[Using Tokens in Cloud Native Build]
(./intro.md#using-tokens-in-cloud-native-build-and-cloud-native-development).

> The pipeline examples below include credential configuration as the first stage for direct copy-paste.
> To split credential setup into a reusable pipeline, see [include](../build/grammar.md#include).

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: docker.cnb.cool/examples/language/gcc-13.4
      stages:
        - name: Configure Conan credentials
          script:
            - conan remote add cnb-conan-repo https://conan.cnbprod.alpha.qq.com/cnb/conan-repo/-/packages/
            - conan remote login -p ${CNB_TOKEN} cnb-conan-repo ${CNB_TOKEN_USER_NAME}
        - name: Build Conan package
          script: conan create . --user=test-user --channel=test-channel
        - name: Upload Conan package
          script: conan upload my-project/1.0.0@test-user/test-channel -r cnb-conan-repo
        - name: Pull Conan package
          script: conan download my-project/1.0.0@test-user/test-channel -r cnb-conan-repo
```

If you need to use pull and push independently, split the corresponding stages into separate pipelines.

## Workspaces

### Prerequisites

Add the following configuration to your `.cnb.yml` file:

```yaml title=".cnb.yml"
$:
  vscode:
    - docker:
        image: docker.cnb.cool/examples/language/gcc-13.4
      services:
        - vscode
        - docker
      imports:
        - <SECRET_REPO_URL>
```

### Add a Remote and Login

Using the built-in `CNB_TOKEN` (recommended):

```shell
conan remote add cnb-conan-repo https://conan.cnbprod.alpha.qq.com/cnb/conan-repo/-/packages/
conan remote login -p ${CNB_TOKEN} cnb-conan-repo ${CNB_TOKEN_USER_NAME}
```

### Pull Artifacts

```shell
conan download <PACKAGE_NAME> -r <REMOTE_NAME>
```

### Build and Push Artifacts

```shell
conan create . --user=<USER> --channel=<CHANNEL>
conan upload <PACKAGE_NAME> -r <REMOTE_NAME>
```

## FAQ

### Q: Why can't I upload packages to the CNB Conan repository using Conan 1.x?

A: The legacy protocol of Conan 1.x is not supported. If you need to upload
using Conan 1.x, enable revisions first by running
`export CONAN_REVISIONS_ENABLED=True`, then try uploading again.

### Q: Why do I get a 409 error when uploading?

A: Currently only a single recipe revision and a single package revision per
version are retained. Pushing a different revision will be treated as an
overwrite operation. Set your repository's overwrite policy to "Allow
Overwrites", or change the package version and try again.

### Q: Why do I get a 400 error when uploading?

A: This usually means the package name doesn't conform to Conan 2 naming conventions. Please verify and retry.

## More Information

For more Conan usage, please refer to the [official documentation](https://docs.conan.io/).