Conan package repository documentation

Docs describing the initial MVC behavior of the GitLab
conan package repository.

This incluses functions for upload, install, search, info,
and remove.

doc/README.md

@@ -258,6 +258,7 @@ The following documentation relates to the DevOps **Package** stage:
 |:----------------------------------------------------------------|:-------------------------------------------------------|
 | [Container Registry](user/packages/container_registry/index.md)   | The GitLab Container Registry enables every project in GitLab to have its own space to store [Docker](https://www.docker.com/) images. |
 | [Dependency Proxy](user/packages/dependency_proxy/index.md) **(PREMIUM)** | The GitLab Dependency Proxy sets up a local proxy for frequently used upstream images/packages. |
+| [Conan Repository](user/packages/conan_repository/index.md) **(PREMIUM)** | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. |
 | [Maven Repository](user/packages/maven_repository/index.md) **(PREMIUM)** | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. |
 | [NPM Registry](user/packages/npm_registry/index.md) **(PREMIUM)**  | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. |
 

doc/administration/geo/replication/index.md

@@ -281,6 +281,7 @@ You can keep track of the progress to include the missing items in:
 | [Container Registry](../../packages/container_registry.md) | Yes | No |
 | [NPM Registry](../../../user/packages/npm_registry/index.md) | No | No |
 | [Maven Packages](../../../user/packages/maven_repository/index.md) | No | No |
+| [Conan Packages](../../../user/packages/conan_repository/index.md) | No | No |
 | [External merge request diffs](../../merge_request_diffs.md) | No, if they are on-disk | No |
 | Content in object storage ([track progress](https://gitlab.com/groups/gitlab-org/-/epics/1526)) | No | No |
 

doc/administration/packages/index.md

@@ -8,6 +8,7 @@ The Packages feature allows GitLab to act as a repository for the following:
 
 | Software repository | Description | Available in GitLab version |
 | ------------------- | ----------- | --------------------------- |
+| [Conan Repository](../../user/packages/conan_repository/index.md) | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.4+ |
 | [Maven Repository](../../user/packages/maven_repository/index.md) | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ |
 | [NPM Registry](../../user/packages/npm_registry/index.md)   | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ |
 

doc/ci/introduction/index.md

@@ -190,6 +190,7 @@ according to each stage (Verify, Package, Release).
    - Store Docker images with [Container Registry](../../user/packages/container_registry/index.md).
    - Store NPM packages with [NPM Registry](../../user/packages/npm_registry/index.md). **(PREMIUM)**
    - Store Maven artifacts with [Maven Repository](../../user/packages/maven_repository/index.md). **(PREMIUM)**
+   - Store Conan packages with [Conan Repository](../../user/packages/conan_repository/index.md). **(PREMIUM)**
 1. **Release**:
    - Continuous Deployment, automatically deploying your app to production.
    - Continuous Delivery, manually click to deploy your app to production.

doc/user/packages/conan_repository/index.md

+# GitLab Conan Repository **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/8248) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4.
+
+With the GitLab Conan Repository, every
+project can have its own space to store Conan packages.
+
+![GitLab Conan Repository](img/conan_package_view.png)
+
+## Enabling the Conan Repository
+
+NOTE: **Note:**
+This option is available only if your GitLab administrator has
+[enabled support for the Conan Repository](../../../administration/packages/index.md).**(PREMIUM ONLY)**
+
+After the Conan Repository is enabled, it will be 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 > Permissions**.
+1. Find the Packages feature and enable or disable it.
+1. Click on **Save changes** for the changes to take effect.
+
+You should then be able to see the **Packages** section on the left sidebar.
+
+Before proceeding to authenticating with the GitLab Conan Repository, you should
+get familiar with the package naming convention.
+
+## Authenticating to the GitLab Conan Repository
+
+You will need to generate a [personal access token](../../../user/profile/personal_access_tokens.md) for repository authentication.
+
+Now you can run conan commands using your token.
+
+`CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload Hello/0.2@user/channel --remote=gitlab`
+`CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan search Hello* --all --remote=gitlab`
+
+Alternatively, you can set the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` in your local conan config to be used when connecting to the `gitlab` remote. The examples here show the username and password inline.
+
+Next, you'll need to set your Conan remote to point to the GitLab Package Registry.
+
+## Setting the Conan remote to the GitLab Package Registry
+
+After you authenticate to the [GitLab Conan Repository](#authenticating-to-the-gitlab-conan-repository),
+you can set the Conan remote:
+
+```sh
+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:
+
+```sh
+conan search Hello* --all --remote=gitlab
+```
+
+## 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 `conan.txt` file.
+- `conan search`: Search the GitLab Package Registry for public packages, and private packages you have permission to view.
+- `conan info`: View the info on a given package from the GitLab Package Registry.
+- `conan remove`: Delete the package from the GitLab Package Registry.
+
+## Uploading a package
+
+First you need to [create your Conan package locally](https://docs.conan.io/en/latest/creating_packages/getting_started.html). In order to work with the GitLab Package Registry, a specific [naming convention](#package-recipe-naming-convention) must be followed.
+
+Ensure you have a project created on GitLab and that the personal access token you are 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).
+
+You can upload your package to the GitLab Package Registry using the `conan upload` command:
+
+```sh
+CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload Hello/0.1@my-group+my-project/beta --all --remote=gitlab
+```
+
+### Package recipe naming convention
+
+Standard Conan recipe convention looks like `package_name/version@username/channel`.
+
+**Recipe usernames must be the `+` separated project path**. The package
+name may be anything, but it is preferred that the project name be used unless
+it is not possible due to a naming collision. For example:
+
+| 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        |
+
+NOTE: **Note:**
+A future iteration will extend support to [project and group level](https://gitlab.com/gitlab-org/gitlab/issues/11679) remotes which will allow for more flexible naming conventions.
+
+## Installing a package
+
+Add the conan package to the `[requires]` section of your `conan.txt` file and they will be installed when you run `conan install` within your project.
+
+## 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:**
+
+  ```sh
+  CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan remove Hello/0.2@user/channel -r gitlab
+  ```
+
+  NOTE: **Note:**
+  This command will remove 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 (e.g., `my-packa*`):
+
+```sh
+CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan search Hello --all --remote=gitlab
+CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan search He* --all --remote=gitlab
+CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan search Hello/1.0.0@my-group+my-project/stable --all --remote=gitlab
+```
+
+The scope of your search will include all projects you have permission to access, this includes your private projects as well as all public projects.
+
+## Fetching Conan package info from the GitLab Package Registry
+
+The `conan info` command will return info about a given package:
+
+```sh
+CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan info Hello/1.0.0@my-group+my-project/stable -r gitlab
+```

doc/user/packages/index.md

@@ -10,6 +10,7 @@ The Packages feature allows GitLab to act as a repository for the following:
 | ------------------- | ----------- | --------------------------- |
 | [Container Registry](container_registry/index.md)   | The GitLab Container Registry enables every project in GitLab to have its own space to store [Docker](https://www.docker.com/) images. | 8.8+ |
 | [Dependency Proxy](dependency_proxy/index.md) **(PREMIUM)** | The GitLab Dependency Proxy sets up a local proxy for frequently used upstream images/packages. | 11.11+ |
+| [Conan Repository](conan_repository/index.md) **(PREMIUM)** | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.4+ |
 | [Maven Repository](maven_repository/index.md) **(PREMIUM)** | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ |
 | [NPM Registry](npm_registry/index.md) **(PREMIUM)**  | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ |
 

doc/user/permissions.md

@@ -76,8 +76,8 @@ The following table depicts the various user permission levels in a project.
 | See a list of merge requests                      |         | ✓          | ✓           | ✓        | ✓      |
 | View project statistics                           |         | ✓          | ✓           | ✓        | ✓      |
 | View Error Tracking list                          |         | ✓          | ✓           | ✓        | ✓      |
-| Pull from [Maven repository](packages/maven_repository/index.md) or [NPM registry](packages/npm_registry/index.md) **(PREMIUM)** |         | ✓          | ✓           | ✓        | ✓      |
-| Publish to [Maven repository](packages/maven_repository/index.md) or [NPM registry](packages/npm_registry/index.md) **(PREMIUM)** |         |            | ✓           | ✓        | ✓      |
+| Pull from [Conan repository](packages/conan_repository/index.md), [Maven repository](packages/maven_repository/index.md), or [NPM registry](packages/npm_registry/index.md) **(PREMIUM)** |         | ✓          | ✓           | ✓        | ✓      |
+| Publish to [Conan repository](packages/conan_repository/index.md), [Maven repository](packages/maven_repository/index.md), or [NPM registry](packages/npm_registry/index.md) **(PREMIUM)** |         |            | ✓           | ✓        | ✓      |
 | Upload [Design Management](project/issues/design_management.md) files **(PREMIUM)** |         |            | ✓           | ✓        | ✓      |
 | Create new branches                               |         |            | ✓           | ✓        | ✓      |
 | Push to non-protected branches                    |         |            | ✓           | ✓        | ✓      |

doc/user/project/index.md

@@ -95,6 +95,7 @@ When you create a project in GitLab, you'll have access to a large number of
 - [Releases](releases/index.md): a way to track deliverables in your project as snapshot in time of
   the source, build output, and other metadata or artifacts
   associated with a released version of your code.
+- [Conan packages](../packages/conan_repository/index.md): your private Conan repository in GitLab. **(PREMIUM)**
 - [Maven packages](../packages/maven_repository/index.md): your private Maven repository in GitLab. **(PREMIUM)**
 - [NPM packages](../packages/npm_registry/index.md): your private NPM package registry in GitLab. **(PREMIUM)**
 - [Code owners](code_owners.md): specify code owners for certain files **(STARTER)**