Conan packages in the Package Registry

Introduced in GitLab Premium 12.6.

Moved to GitLab Core in 13.3.

Publish Conan packages in your project’s Package Registry. Then install the packages whenever you need to use them as a dependency.

To publish Conan packages to the Package Registry, add the Package Registry as a remote and authenticate with it.

Then you can run conan commands and publish your package to the Package Registry.

Build a Conan package

This section explains how to install Conan and build a package for your C/C++ project.

If you already use Conan and know how to build your own packages, go to the next section.

Install Conan

Download the Conan package manager to your local development environment by following the instructions at conan.io.

When installation is complete, verify you can use Conan in your terminal by running:

conan --version

The Conan version is printed in the output:

Conan version 1.20.5

Install CMake

When you develop with C++ and Conan, you can select from many available compilers. This example uses the CMake build system generator.

To install CMake:

For Mac, use Homebrew and run brew install cmake.
For other operating systems, follow the instructions at cmake.org.

When installation is complete, verify you can use CMake in your terminal by running:

cmake --version

The CMake version is printed in the output.

Create a project

To test the Package Registry, you need a C++ project. If you don't already have one, you can clone the Conan hello world starter project.

Build a package

To build a package:

Open a terminal and navigate to your project's root folder.
Generate a new recipe by running conan new with a package name and version:
```
conan new Hello/0.1 -t
```
Create a package for the recipe by running conan create with the Conan user and channel:
```
conan create . mycompany/beta
```
NOTE: If you use an instance remote, you must follow a specific naming convention.

A package with the recipe Hello/0.1@mycompany/beta is created.

For more details about creating and managing Conan packages, see the Conan documentation.

Add the Package Registry as a Conan remote

To run conan commands, you must add the Package Registry as a Conan remote for your project or instance.

Add a remote for your project

Introduced in GitLab 13.4.

Set a remote so you can work with packages in a project without having to specify the remote name in every command.

When you set a remote for a project, there are no restrictions to your package names. However, your commands must include the full recipe, including the user and channel, for example, package_name/version@user/channel.

To add the remote:

In your terminal, run this command:

conan remote add gitlab https://gitlab.example.com/api/v4/projects/<project_id>/packages/conan

Use the remote by adding --remote=gitlab to the end of your Conan command.

For example:
```
conan search Hello* --all --remote=gitlab
```

Add a remote for your instance

Use a single remote to access packages across your entire GitLab instance.

However, when using this remote, you must follow these package naming restrictions.

To add the remote:

In your terminal, run this command:

conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan

Use the remote by adding --remote=gitlab to the end of your Conan command.

For example:
```
conan search 'Hello*' --remote=gitlab
```

Package recipe naming convention for instance remotes

The standard Conan recipe convention is package_name/version@user/channel, but if you're using an instance remote, the recipe user must be the plus sign (+) separated project path.

Example recipe names:

Project	Package	Supported
`foo/bar`	`my-package/1.0.0@foo+bar/stable`	Yes
`foo/bar-baz/buz`	`my-package/1.0.0@foo+bar-baz+buz/stable`	Yes
`gitlab-org/gitlab-ce`	`my-package/1.0.0@gitlab-org+gitlab-ce/stable`	Yes
`gitlab-org/gitlab-ce`	`my-package/1.0.0@foo/stable`	No

Project remotes have a more flexible naming convention.

Authenticate to the Package Registry

To authenticate to the Package Registry, you need either a personal access token or deploy token.

If you use a personal access token, set the scope to api.
If you use a deploy token, set the scope to read_package_registry, write_package_registry, or both.

Add your credentials to the GitLab remote

Associate your token with the GitLab remote, so that you don't have to explicitly add a token to every Conan command.

Prerequisites:

You must have an authentication token.
The Conan remote must be configured.

In a terminal, run this command. In this example, the remote name is gitlab. Use the name of your remote.

conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_access_token or deploy_token>

Now when you run commands with --remote=gitlab, your username and password are included in the requests.

Alternatively, you can explicitly include your credentials in any given command. For example:

CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> conan upload Hello/0.1@mycompany/beta --all --remote=gitlab

NOTE: Because your authentication with GitLab expires on a regular basis, you may occasionally need to re-enter your personal access token.

Set a default remote for your project (optional)

If you want to interact with the GitLab Package Registry without having to specify a remote, you can tell Conan to always use the Package Registry for your packages.

In a terminal, run this command:

conan remote add_ref Hello/0.1@mycompany/beta gitlab

NOTE: The package recipe includes the version, so the default remote for Hello/0.1@user/channel doesn't work for Hello/0.2@user/channel.

If you don't set a default user or remote, you can still include the user and remote in your commands:

`CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> <conan command> --remote=gitlab

Publish a Conan package

Publish a Conan package to the Package Registry, so that anyone who can access the project can use the package as a dependency.

Prerequisites:

The Conan remote must be configured.
Authentication with the Package Registry must be configured.
A local Conan package must exist.
- For an instance remote, the package must meet the naming convention.
You must have the project ID, which is on the project's homepage.

To publish the package, use the conan upload command:

conan upload Hello/0.1@mycompany/beta --all

Publish a Conan package by using CI/CD

Introduced in GitLab Premium 12.7.

To work with Conan commands in GitLab CI/CD, you can use CI_JOB_TOKEN in place of the personal access token in your commands.

You can provide the CONAN_LOGIN_USERNAME and CONAN_PASSWORD with each Conan command in your .gitlab-ci.yml file. For example:

image: conanio/gcc7

create_package:
  stage: deploy
  script:
    - conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan
    - conan new <package-name>/0.1 -t
    - conan create . <group-name>+<project-name>/stable
    - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload <package-name>/0.1@<group-name>+<project-name>/stable --all --remote=gitlab

Additional Conan images to use as the basis of your CI file are available in the Conan docs.

Install a Conan package

Install a Conan package from the Package Registry so you can use it as a dependency.

WARNING: Project-level packages cannot be downloaded currently.

Conan packages are often installed as dependencies by using the conanfile.txt file.

Prerequisites:

The Conan remote must be configured.
Authentication with the Package Registry must be configured.

In the project where you want to install the package as a dependency, open conanfile.txt. Or, in the root of your project, create a file called conanfile.txt.

Add the Conan recipe to the [requires] section of the file:

[requires]
Hello/0.1@mycompany/beta

[generators]
cmake

At the root of your project, create a build directory and change to that directory:
```
mkdir build && cd build
```
Install the dependencies listed in conanfile.txt:
```
conan install .. <options>
```

NOTE: If you try to install the package you just created in this tutorial, the package already exists on your local computer, so this command has no effect.

Remove a Conan package

There are two ways to remove a Conan package from the GitLab Package Registry.

From the command line, using the Conan client:
```
conan remove Hello/0.2@user/channel --remote=gitlab
```
You must explicitly include the remote in this command, otherwise the package is removed only from your local system cache.

NOTE: This command removes all recipe and binary package files from the Package Registry.
From the GitLab user interface:

Go to your project's Packages & Registries > Package Registry. Remove the package by clicking the red trash icon.

Search for Conan packages in the Package Registry

To search by full or partial package name, or by exact recipe, run the conan search command.

To search for all packages with a specific package name:
```
conan search Hello --remote=gitlab
```
To search for a partial name, like all packages starting with He:
```
conan search He* --remote=gitlab
```

The scope of your search includes all projects you have permission to access. This includes your private projects as well as all public projects.

Fetch Conan package information from the Package Registry

The conan info command returns information about a package:

conan info Hello/0.1@mycompany/beta

Supported CLI commands

The GitLab Conan repository supports the following Conan CLI commands:

conan upload: Upload your recipe and package files to the Package Registry.
conan install: Install a Conan package from the Package Registry, which includes using the conanfile.txt file.
conan search: Search the Package Registry for public packages, and private packages you have permission to view.
conan info: View the information on a given package from the Package Registry.
conan remove: Delete the package from the Package Registry.

Troubleshooting Conan packages

`ERROR: <package> was not found in remote <remote>`

When you attempt to install a Conan package, you might receive a 404 error like ERROR: <package> was not found in remote <remote>.

This issue occurs when you request a download from the project-level Conan API. The resulting URL is missing is project's /<id> and Conan commands, like conan install, fail.

For more information, see issue 270129.