- Build a Conan package
- Add the Package Registry as a Conan remote
- Authenticate to the Package Registry
- Publish a Conan package
- Publish a Conan package by using CI/CD
- Install a Conan package
- Remove a Conan package
- Search for Conan packages in the Package Registry
- Fetch Conan package information from the Package Registry
- Supported CLI commands
- Troubleshooting
Conan packages in the Package Registry
- Introduced in GitLab 12.6.
- Moved from GitLab Premium to GitLab Free 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.
For documentation of the specific API endpoints that the Conan package manager client uses, see the Conan API documentation.
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
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.
Package without a username and a channel
- Introduced in GitLab 14.6.
Even though they are recommended to distinguish your package from a similarly named existing package, the username and channel are not mandatory fields for a Conan package.
You can create a package without a username and channel by removing them from
the create
command:
conan create .
The username and the channel must be blank. If only one of these fields is blank, the request is rejected.
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. Then you can publish packages to
and install packages from the Package Registry.
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* --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
GitLab requires authentication to upload packages, and to install packages from private and internal projects. (You can, however, install packages from public projects without authentication.)
To authenticate to the Package Registry, you need one of the following:
- A personal access token
with the scope set to
api
. - A deploy token with the
scope set to
read_package_registry
,write_package_registry
, or both. - A CI job token.
unable to find the package in remote
in the Conan client.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.
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
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 12.7.
- Moved from GitLab Premium to GitLab Free in 13.3.
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: