@@ -446,7 +446,7 @@ package manager. For a comprehensive list, consult [the Conan documentation](htt
The default [Conan](https://conan.io/) configuration sets [`CONAN_LOGIN_USERNAME`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name)
to `ci_user`, and binds [`CONAN_PASSWORD`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-password-conan-password-remote-name)
to the [`CI_JOB_TOKEN`](../../../ci/variables/predefined_variables.md)
for the running job. This allows Conan projects to fetch packages from a [GitLab Conan Repository](../../packages/conan_repository/#fetching-conan-package-information-from-the-gitlab-package-registry)
for the running job. This allows Conan projects to fetch packages from a [GitLab Conan Repository](../../packages/conan_repository/#fetch-conan-package-information-from-the-package-registry)
if a GitLab remote is specified in the `.conan/remotes.json` file.
To override the default credentials specify a [`CONAN_LOGIN_USERNAME_{REMOTE_NAME}`](https://docs.conan.io/en/latest/reference/env_vars.html#conan-login-username-conan-login-username-remote-name)
info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# GitLab Conan Repository
# Conan packages in the Package Registry
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6.
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3.
With the GitLab Conan Repository, every
project can have its own space to store Conan packages.
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.
## Enabling the Conan Repository
Then you can run `conan` commands and publish your package to the Package Registry.
NOTE: **Note:**
This option is available only if your GitLab administrator has
[enabled support for the Conan Repository](../../../administration/packages/index.md).
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**.
1. Find the Packages feature and enable or disable it.
1. Click on **Save changes** for the changes to take effect.
## Build a Conan package
You should then be able to see the **Packages & Registries** section on the left sidebar.
This section explains how to install Conan and build a package for your C/C++ project.
## Getting started
If you already use Conan and know how to build your own packages, go to the [next section](#add-the-package-registry-as-a-conan-remote).
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](#adding-the-gitlab-package-registry-as-a-conan-remote).
### Install Conan
### Installing Conan
Download the Conan package manager to your local development environment by following
the instructions at [conan.io](https://conan.io/downloads.html).
Follow the instructions at [conan.io](https://conan.io/downloads.html) 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
When installation is complete, verify you can use Conan in your terminal by running:
```shell
conan --version
```
You should see the Conan version printed in the output:
The Conan version is printed in the output:
```plaintext
Conan version 1.20.5
```
### Installing CMake
### Install CMake
When you develop with C++ and Conan, you have a range of compilers to choose from.
This example uses the CMake compiler.
To install 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
- For Mac, use [homebrew](https://brew.sh/) and run `brew install cmake`.
- For other operating systems, follow the instructions at [cmake.org](https://cmake.org/install/).
When installation is complete, verify you can use CMake in your terminal by running:
```shell
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](https://brew.sh/) to install cmake by running `brew install cmake`. Otherwise, follow
instructions at [cmake.org](https://cmake.org/install/) for your operating system.
### Creating a project
The CMake version is printed in the output.
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](https://github.com/conan-io/hello) that you can clone to get started.
### Create a project
Clone the repository and it can be used for the rest of the tutorial if you don't have your own C++ 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](https://github.com/conan-io/hello).
### Building a package
### Build 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:
To build a package:
```shell
conan new Hello/0.1 -t
```
1. Open a terminal and navigate to your project's root folder.
1. Generate a new recipe by running `conan new` with a package name and version:
Next, create a package for that recipe by running `conan create` providing the Conan user and channel:
```shell
conan new Hello/0.1 -t
```
```shell
conan create . mycompany/beta
```
1. Create a package for the recipe by running `conan create` with the Conan user and channel:
NOTE: **Note:**
If you are using the [instance level remote](#instance-level-remote), a specific [naming convention](#package-recipe-naming-convention-for-instance-level-remote) must be followed.
```shell
conan create . mycompany/beta
```
These two example commands generate a final package with the recipe `Hello/0.1@mycompany/beta`.
NOTE: **Note:**
If you use an [instance remote](#add-a-remote-for-your-instance), you must follow a specific [naming convention](#package-recipe-naming-convention-for-instance-remotes).
For more advanced details on creating and managing your packages, refer to the [Conan docs](https://docs.conan.io/en/latest/creating_packages.html).
A package with the recipe `Hello/0.1@mycompany/beta` is created.
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.
For more details on creating and managing Conan packages, see the [Conan docs](https://docs.conan.io/en/latest/creating_packages.html).
## Adding the GitLab Package Registry as a Conan remote
## Add the Package Registry as a Conan remote
You can add the GitLab Package Registry as a Conan remote at the project or instance level.
To run `conan` commands, you must add the Package Registry as a Conan remote for your project or instance.
### Project level remote
### Add a remote for your project
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11679) in GitLab 13.4.
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`).
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,
| `gitlab-org/gitlab-ce` | `my-package/1.0.0@foo/stable` | No |
NOTE: **Note:**
[Project level remotes](#project-level-remote) allow for more flexible package names.
[Project remotes](#add-a-remote-for-your-project) 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.
## Authenticating to the GitLab Conan Repository
- If you use a [personal access token](../../../user/profile/personal_access_tokens.md), set the scope to `api`.
- If you use a [deploy token](./../../project/deploy_tokens/index.md), set the scope to `read_package_registry`, `write_package_registry`, or both.
You need a personal access token or deploy token.
### Add your credentials to the GitLab remote
For repository authentication:
Associate your token with the GitLab remote, so that you don't have to explicitly
add a token to every Conan command.
- You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api`.
- You can generate a [deploy token](./../../project/deploy_tokens/index.md) with the scope set to `read_package_registry`, `write_package_registry`, or both.
Prerequisites:
### Adding a Conan user to the GitLab remote
- You must have an authentication token.
- The Conan remote [must be set](#add-the-package-registry-as-a-conan-remote).
Once you have a personal access token and have [set your Conan remote](#adding-the-gitlab-package-registry-as-a-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:
In a terminal, run this command. In this example, the remote name is `gitlab`. Use the name of your remote.
```shell
conan user <gitlab_username or deploy_token_username> -r gitlab -p <personal_access_token or deploy_token>
```
NOTE: **Note:**
If you named your remote something other than `gitlab`, your remote name should be used in this command instead of `gitlab`.
From now on, when you run commands using `--remote=gitlab`, your username and password is automatically included in the requests.
NOTE: **Note:**
The personal access token is not stored locally at any moment. Conan uses JSON Web Tokens (JWT), so when you run this command, Conan requests an expirable token from GitLab using your token. The JWT does expire on a regular basis, so you need to re-enter your personal access token when that happens.
Now when you run commands with `--remote=gitlab`, your username and password are automatically included in the requests.
Alternatively, you could explicitly include your credentials in any given command.
For example:
Alternately, you can explicitly include your credentials in any given command. For example:
```shell
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)
NOTE: **Note:**
Your authentication with GitLab expires on a regular basis,
so occasionally you may need to re-enter your personal access token.
### Set a default remote for 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:
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.
The package recipe does include the version, so setting the default remote for `Hello/0.1@user/channel` will not work for `Hello/0.2@user/channel`.
This functionality is best suited for when you want to consume or install packages from the GitLab registry without having to specify a remote.
The package recipe includes the version, so the default remote for `Hello/0.1@user/channel` does not work for `Hello/0.2@user/channel`.
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:
If you do not set a default user or remote, you can still include the user and remote in your commands:
```shell
`CONAN_LOGIN_USERNAME=<gitlab_username or deploy_token_username> CONAN_PASSWORD=<personal_access_token or deploy_token> <conan command>--remote=gitlab
```
## Uploading a package
## Publish a Conan package
First you need to [create your Conan package locally](https://docs.conan.io/en/latest/creating_packages/getting_started.html).
Publish a Conan package to the Package Registry, so that anyone who can access the project can use the package as a dependency.
NOTE: **Note:**
If you are using the [instance level remote](#instance-level-remote), a specific [naming convention](#package-recipe-naming-convention-for-instance-level-remote) must be followed.
Prerequisites:
To publish a Conan package, you need:
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](../../../user/profile/personal_access_tokens.md#limiting-scopes-of-a-personal-access-token).
- The Package Registry [set as a remote](#add-the-package-registry-as-a-conan-remote).
-[Authentication](#authenticate-to-the-package-registry) set up with the Package Registry.
- A local [Conan package](https://docs.conan.io/en/latest/creating_packages/getting_started.html).
- For an instance remote, the package must meet the [naming convention](#package-recipe-naming-convention-for-instance-remotes).
- A project ID, which is on the project's homepage.
You can upload your package to the GitLab Package Registry using the `conan upload` command:
To publish the package, use the `conan upload` command:
```shell
conan upload Hello/0.1@mycompany/beta --all
```
## Installing a package
## Publish a Conan package by using CI/CD
Conan packages are commonly installed as dependencies using the `conanfile.txt` file.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11678) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7.
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.
To work with Conan commands in [GitLab CI/CD](./../../../ci/README.md), you can use
`CI_JOB_TOKEN` in place of the personal access token in your commands.
Add the Conan recipe to the `[requires]` section of the file:
You can provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each
Conan command in your `.gitlab-ci.yml` file. For example:
@@ -31,7 +31,7 @@ authenticate with GitLab by using the `CI_JOB_TOKEN`.
CI/CD templates, which you can use to get started, are in [this repo](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates).
Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd), [Composer packages](../composer_repository/index.md#publish-a-composer-package-by-using-cicd), [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd), [Conan Packages](../conan_repository/index.md#using-gitlab-ci-with-conan-packages), and [PyPI packages](../pypi_repository/index.md#using-gitlab-ci-with-pypi-packages).
Learn more about [using CI/CD to build Maven packages](../maven_repository/index.md#creating-maven-packages-with-gitlab-cicd), [NPM packages](../npm_registry/index.md#publishing-a-package-with-cicd), [Composer packages](../composer_repository/index.md#publish-a-composer-package-by-using-cicd), [NuGet Packages](../nuget_repository/index.md#publishing-a-nuget-package-with-cicd), [Conan Packages](../conan_repository/index.md#publish-a-conan-package-by-using-cicd), and [PyPI packages](../pypi_repository/index.md#using-gitlab-ci-with-pypi-packages).
If you use CI/CD to build a package, extended activity
information is displayed when you view the package details:
@@ -80,11 +80,11 @@ Now you can [deploy Maven packages](../maven_repository/index.md#uploading-packa
#### Conan
For Conan, first you need to add GitLab as a Conan registry remote. Follow the instructions in the [GitLab Conan Repository docs](../conan_repository/index.md#adding-the-gitlab-package-registry-as-a-conan-remote)
For Conan, first you need to add GitLab as a Conan registry remote. Follow the instructions in the [GitLab Conan Repository docs](../conan_repository/index.md#add-the-package-registry-as-a-conan-remote)
to do so. Then, create your package using the plus-separated (`+`) project path as your Conan user. For example,
if your project is located at `https://gitlab.com/foo/bar/my-proj`, then you can [create your Conan package](../conan_repository/index.md)
using `conan create . foo+bar+my-proj/channel`, where `channel` is your package channel (`stable`, `beta`, etc.). Once your package
is created, you are ready to [upload your package](../conan_repository/index.md#uploading-a-package) depending on your final package recipe. For example:
is created, you are ready to [upload your package](../conan_repository/index.md#publish-a-conan-package) depending on your final package recipe. For example:
