• Enabling the Conan Repository
• Getting started
  • Installing Conan
  • Installing CMake
  • Creating a project
  • Building a package
• Adding the GitLab Package Registry as a Conan remote
  • Project level remote
  • Instance level remote
    • Package recipe naming convention for instance level remote
• Authenticating to the GitLab Conan Repository
  • Adding a Conan user to the GitLab remote
  • Setting a default remote to your project (optional)
• Uploading a package
• Installing a package
• Removing a package
• Searching the GitLab Package Registry for Conan packages
• Fetching Conan package information from the GitLab Package Registry
• List of supported CLI commands
• Using GitLab CI with Conan packages

GitLab Conan Repository

With the GitLab Conan Repository, every project can have its own space to store Conan packages.

Enabling the Conan Repository

After the Conan Repository is enabled, it’s available for all new projects by default. To enable it for existing projects, or if you want to disable it:

1. Navigate to your project’s Settings > General > Visibility, project features, permissions.
2. Find the Packages feature and enable or disable it.
3. Click on Save changes for the changes to take effect.

You should then be able to see the Packages & Registries section on the left sidebar.

Getting started

This section covers installing Conan and building a package for your C/C++ project. This is a quickstart if you’re new to Conan. If you already are using Conan and understand how to build your own packages, move on to the next section.

Installing Conan

Follow the instructions at conan.io to download the Conan package manager to your local development environment.

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

conan --version

You should see the Conan version printed in the output:

Conan version 1.20.5

Installing CMake

When developing with C++ and Conan, you have a wide range of options for compilers. This tutorial walks through using the cmake compiler. In your terminal, run the command

cmake --version

You should see the cmake version printed in the output. If you see something else, you may have to install cmake.

On a Mac, you can use homebrew to install cmake by running brew install cmake. Otherwise, follow instructions at cmake.org for your operating system.

Creating a project

Understanding what is needed to create a valid and compilable C++ project is out of the scope of this guide, but if you’re new to C++ and want to try out the GitLab package registry, Conan.io has a great hello world starter project that you can clone to get started.

Clone the repository and it can be used for the rest of the tutorial if you don’t have your own C++ project.

Building a package

In your terminal, navigate to the root folder of your project. Generate a new recipe by running conan new and providing it with a package name and version:

conan new Hello/0.1 -t

Next, create a package for that recipe by running conan create providing the Conan user and channel:

conan create . mycompany/beta

These two example commands generate a final package with the recipe Hello/0.1@mycompany/beta.

For more advanced details on creating and managing your packages, refer to the Conan docs.

You are now ready to upload your package to the GitLab registry. To get started, first you need to set GitLab as a remote. Then you need to add a Conan user for that remote to authenticate your requests.

Adding the GitLab Package Registry as a Conan remote

You can add the GitLab Package Registry as a Conan remote at the project or instance level.

Project level remote

The project level remote allows you to work with packages within a given project. The advantage of using the project level remote is there are no restrictions to your package name, however all GitLab Conan packages require a full recipe with the user and channel (package_name/version@user/channel).

To add the remote:

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

Once the remote is set, you can use the remote when running Conan commands by adding --remote=gitlab to the end of your commands.

For example:

conan search Hello* --all --remote=gitlab

Instance level remote

The instance level remote allows you to use a single remote to access packages accross your entire GitLab instance. However, when using this remote, there are certain package naming restrictions that must be followed.

Add a new remote to your Conan configuration:

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

Once the remote is set, you can use the remote when running Conan commands by adding --remote=gitlab to the end of your commands.

For example:

conan search 'Hello*' --remote=gitlab

Package recipe naming convention for instance level remote

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

The following table shows some example recipes you can give your package based on the project name and path.

Authenticating to the GitLab Conan Repository

You need a personal access token or deploy token.

For repository authentication:

• You can generate a personal access token with the scope set to api.
• You can generate a deploy token with the scope set to read_package_registry, write_package_registry, or both.

Adding a Conan user to the GitLab remote

Once you have a personal access token and have set your Conan remote, you can associate the token with the remote so you don’t have to explicitly add them to each Conan command you run:

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

From now on, when you run commands using --remote=gitlab, your username and password is automatically included in the requests.

Alternatively, you could 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

Setting a default remote to your project (optional)

If you’d like Conan to always use GitLab as the registry for your package, you can tell Conan to always reference the GitLab remote for a given package recipe:

conan remote add_ref Hello/0.1@mycompany/beta gitlab

The rest of the example commands in this documentation assume that you’ve added a Conan user with your credentials to the gitlab remote and will not include the explicit credentials or remote option. With that said, be aware that any of the commands could be run without having added a user or default remote:

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

Uploading a package

First you need to create your Conan package locally.

Ensure you have a project created on GitLab and that the personal access token you’re using has the correct permissions for write access to the container registry by selecting the api scope.

You can upload your package to the GitLab Package Registry using the conan upload command:

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

Installing a package

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

In your project where you would like to install the Conan package as a dependency, open conanfile.txt or create an empty file named conanfile.txt in the root of your project.

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

 [requires]
 Hello/0.1@mycompany/beta

 [generators]
 cmake

Next, create a build directory from the root of your project and navigate to it:

mkdir build && cd build

Now you can install the dependencies listed in conanfile.txt:

conan install ..

Removing a package

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

• Using the Conan client in the command line:

  conan remove Hello/0.2@user/channel --remote=gitlab
  

  You need to explicitly include the remote in this command, otherwise the package is only removed from your local system cache.

  Note: This command removes all recipe and binary package files from the Package Registry.

• GitLab project interface: in the packages view of your project page, you can delete packages by clicking the red trash icons.

Searching the GitLab Package Registry for Conan packages

The conan search command can be run searching by full or partial package name, or by exact recipe.

To search using a partial name, use the wildcard symbol *, which should be placed at the end of your search (for example, my-packa*):

conan search Hello --all --remote=gitlab
conan search He* --all --remote=gitlab
conan search Hello/0.1@mycompany/beta --all --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.

Fetching Conan package information from the GitLab Package Registry

The conan info command returns information about a given package:

conan info Hello/0.1@mycompany/beta

List of supported CLI commands

The GitLab Conan repository supports the following Conan CLI commands:

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

Using GitLab CI with Conan packages

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

It’s easiest to 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

You can find additional Conan images to use as the base of your CI file in the Conan docs.