doc/user/packages/conan_1_repository/_index.md
{{< details >}}
{{< /details >}}
[!warning] The Conan package registry for GitLab is under development and isn't ready for production use due to limited functionality. This epic details the remaining work and timelines to make it production ready.
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.
[!note] The Conan registry is not FIPS compliant and is disabled when FIPS mode is enabled.
For documentation of the specific API endpoints that the Conan package manager client uses, see Conan v1 API or Conan v2 API.
Learn how to build a Conan 1 package.
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.
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
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
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.
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:
api.read_package_registry, write_package_registry, or both.[!note] Packages from private and internal projects are hidden if you are not authenticated. If you try to search or download a package from a private or internal project without authenticating, you receive the error
unable to find the package in remotein the Conan client.
Associate your token with the GitLab remote, so that you don't have to explicitly add a token to every Conan command.
Prerequisites:
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.
[!note] Because your authentication with GitLab expires on a regular basis, you may occasionally need to re-enter your personal access token.
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/channeldoesn't work forHello/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 to the package registry, so that anyone who can access the project can use the package as a dependency.
Prerequisites:
To publish the package, use the conan upload command:
conan upload Hello/0.1@mycompany/beta --all
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:
create_package:
image: conanio/gcc7
stage: deploy
script:
- conan remote add gitlab ${CI_API_V4_URL}/projects/$CI_PROJECT_ID/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
environment: production
Additional Conan images to use as the basis of your CI file are available in the Conan docs.
When you publish a package that has the same recipe (package-name/version@user/channel)
as an existing package, the duplicate files are uploaded successfully and
are accessible through the UI. However, when the package is installed,
only the most recently-published package is returned.
Install a Conan package from the package registry so you can use it as a dependency. You can install a package from the scope of your instance or your project. If multiple packages have the same recipe, when you install a package, the most recently-published package is retrieved.
Conan packages are often installed as dependencies by using the conanfile.txt
file.
Prerequisites:
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 installing the package you created in this tutorial, the install command has no effect because the package already exists. Delete
~/.conan/datato clean up the packages stored in the cache.
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 Deploy > Package registry. Remove the package by selecting Remove repository ({{< icon name="remove" >}}).
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 depends on your Conan remote configuration:
If you have a remote configured for your instance, your search includes all projects you have permission to access. This includes your private projects as well as all public projects.
If you have a remote configured for a project, your search includes all packages in the target project, as long as you have permission to access it.
The limit of the search results is 500 packages, and the results are sorted by the most recently published packages.
[!note] When searching for packages, the Conan v1 CLI displays only package details for packages uploaded with Conan v1. Packages uploaded with Conan v2 appear in search results, but their details are not shown. This is because Conan v1 expects the
recipe_hashfield in the package reference metadata, which is only present in packages uploaded with Conan v1.
The conan info command returns information about a package:
conan info Hello/0.1@mycompany/beta
[!note] Packages uploaded before Conan info metadata extraction was enabled cannot be downloaded with the
conan downloadCLI command.
You can download a Conan package's recipe and binaries to your local cache without using settings that use the conan download command.
Prerequisites:
You can download all binary packages associated with a recipe from the package registry.
To download all binary packages, run the following command:
conan download Hello/0.1@foo+bar/stable --remote=gitlab
You can download only the recipe files without any binary packages.
To download recipe files, run the following command:
conan download Hello/0.1@foo+bar/stable --remote=gitlab --recipe
You can download a single binary package by referencing its package reference (known as the package_id in Conan documentation).
To download a specific binary package, run the following command:
conan download Hello/0.1@foo+bar/stable:<package_reference> --remote=gitlab
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 download: Download package recipes and binaries to your local cache without using settings.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.{{< history >}}
parse_conan_metadata_on_upload. Disabled by default.parse_conan_metadata_on_upload removed.{{< /history >}}
When you upload a Conan package, GitLab automatically extracts metadata from the conaninfo.txt file. This metadata includes:
os, arch, compiler and build_type)[!note] Packages uploaded before this feature was enabled (GitLab 17.10) do not have their metadata extracted. For these packages, some search and download functionalities are limited.
{{< history >}}
conan_package_revisions_support. Disabled by default.conan_package_revisions_support removed.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.
Conan 1 revisions provide package immutability in the package registry. When you make changes to a recipe or a package without changing its version, Conan calculates a unique identifier (revision) to track these changes.
[!note] Conan 1 revisions are supported only when the remote is setup on a project, not for the entire instance.
Conan uses two types of revisions:
Revisions are not enabled by default in Conan 1.x. To enable revisions, you must either:
revisions_enabled=1 in the [general] section of your _conan.conf_ file (preferred).CONAN_REVISIONS_ENABLED=1 environment variable.You can reference packages in the following formats:
| Reference | Description |
|---|---|
lib/1.0@conan/stable | The latest RREV for lib/1.0@conan/stable. |
lib/1.0@conan/stable#RREV | The specific RREV for lib/1.0@conan/stable. |
lib/1.0@conan/stable#RREV:PACKAGE_REFERENCE | A binary package that belongs to the specific RREV. |
lib/1.0@conan/stable#RREV:PACKAGE_REFERENCE#PREV | A binary package revision PREV that belongs to the specific RREV. |
To upload all revisions and their binaries to the GitLab package registry:
conan upload package_name/version@user/channel#* --all --remote=gitlab
When you upload multiple revisions, they are uploaded from oldest to newest. The relative order is preserved in the registry.
To search for all revisions of a specific recipe in Conan v1:
conan search package_name/version@user/channel --revisions --remote=gitlab
This command displays all available revisions for the specified recipe along with their revision hashes and creation dates.
To get detailed information about a specific revision:
conan search package_name/version@user/channel#revision_hash --remote=gitlab
This command shows you the specific binary packages available for that revision.
You can delete packages at different levels of granularity:
To delete a specific recipe revision and all its associated binary packages:
conan remove package_name/version@user/channel#revision_hash --remote=gitlab
To delete all packages associated with a specific recipe revision:
conan remove package_name/version@user/channel#revision_hash --packages --remote=gitlab
To delete a specific package in a recipe revision, you can use either of these commands:
conan remove package_name/version@user/channel#revision_hash -p package_id --remote=gitlab
Or:
conan remove package_name/version@user/channel#revision_hash:package_id --remote=gitlab
[!note] When you delete packages with revisions, you must include the
--remote=gitlabflag. Otherwise, the package is removed only from your local system cache.
Revisions are designed to be immutable. When you modify a recipe or its source code:
For package binaries, you should include only one package revision per recipe revision and package reference (known as the package_id in Conan documentation). Multiple package revisions for the same recipe revision and package ID indicate that a package was rebuilt unnecessarily.
For more verbose output when troubleshooting a Conan issue:
export CONAN_TRACE_FILE=/tmp/conan_trace.log # Or SET in windows
conan <command>
You can find more logging tips in the Conan documentation.
If you are using a self-signed certificate, there are two methods to manage SSL errors with Conan:
conan remote command to disable the SSL verification.crt file to the cacert.pem file.Read more about this in the Conan Documentation.