Add latest changes from gitlab-org/gitlab@master

.eslintrc.yml

@@ -42,7 +42,6 @@ rules:
   lines-between-class-members: off
   # Disabled for now, to make the plugin-vue 4.5 -> 5.0 update smoother
   vue/no-confusing-v-for-v-if: error
-  vue/no-unused-components: off
   vue/no-use-v-if-with-v-for: off
   vue/no-v-html: off
   vue/use-v-on-exact: off

app/models/ci/build.rb

@@ -23,6 +23,7 @@ module Ci
     belongs_to :runner
     belongs_to :trigger_request
     belongs_to :erased_by, class_name: 'User'
+    belongs_to :resource_group, class_name: 'Ci::ResourceGroup', inverse_of: :builds
     RUNNER_FEATURES = {
       upload_multiple_artifacts: -> (build) { build.publishes_artifacts_reports? },
@@ -34,6 +35,7 @@ module Ci
     }.freeze
     has_one :deployment, as: :deployable, class_name: 'Deployment'
+    has_one :resource, class_name: 'Ci::Resource', inverse_of: :build
     has_many :trace_sections, class_name: 'Ci::BuildTraceSection'
     has_many :trace_chunks, class_name: 'Ci::BuildTraceChunk', foreign_key: :build_id

app/models/ci/resource.rb

+# frozen_string_literal: true
+
+module Ci
+  class Resource < ApplicationRecord
+    extend Gitlab::Ci::Model
+
+    belongs_to :resource_group, class_name: 'Ci::ResourceGroup', inverse_of: :resources
+    belongs_to :build, class_name: 'Ci::Build', inverse_of: :resource
+
+    scope :free, -> { where(build: nil) }
+    scope :retained_by, -> (build) { where(build: build) }
+  end
+end

app/models/ci/resource_group.rb

+# frozen_string_literal: true
+
+module Ci
+  class ResourceGroup < ApplicationRecord
+    extend Gitlab::Ci::Model
+
+    belongs_to :project, inverse_of: :resource_groups
+
+    has_many :resources, class_name: 'Ci::Resource', inverse_of: :resource_group
+    has_many :builds, class_name: 'Ci::Build', inverse_of: :resource_group
+
+    validates :key,
+      length: { maximum: 255 },
+      format: { with: Gitlab::Regex.environment_name_regex,
+                message: Gitlab::Regex.environment_name_regex_message }
+
+    before_create :ensure_resource
+
+    ##
+    # NOTE: This is concurrency-safe method that the subquery in the `UPDATE`
+    # works as explicit locking.
+    def assign_resource_to(build)
+      resources.free.limit(1).update_all(build_id: build.id) > 0
+    end
+
+    def release_resource_from(build)
+      resources.retained_by(build).update_all(build_id: nil) > 0
+    end
+
+    private
+
+    def ensure_resource
+      # Currently we only support one resource per group, which means
+      # maximum one build can be set to the resource group, thus builds
+      # belong to the same resource group are executed once at time.
+      self.resources.build if self.resources.empty?
+    end
+  end
+end

app/models/project.rb

@@ -285,6 +285,7 @@ class Project < ApplicationRecord
   has_many :pipeline_schedules, class_name: 'Ci::PipelineSchedule'
   has_many :project_deploy_tokens
   has_many :deploy_tokens, through: :project_deploy_tokens
+  has_many :resource_groups, class_name: 'Ci::ResourceGroup', inverse_of: :project
   has_one :auto_devops, class_name: 'ProjectAutoDevops', inverse_of: :project, autosave: true
   has_many :custom_attributes, class_name: 'ProjectCustomAttribute'

app/services/ci/retry_build_service.rb

@@ -5,7 +5,7 @@ module Ci
     CLONE_ACCESSORS = %i[pipeline project ref tag options name
                          allow_failure stage stage_id stage_idx trigger_request
                          yaml_variables when environment coverage_regex
-                         description tag_list protected needs].freeze
+                         description tag_list protected needs resource_group].freeze
     def execute(build)
       reprocess!(build).tap do |new_build|

changelogs/unreleased/ci-resource-group-model.yml

+---
+title: Add Ci Resource Group models
+merge_request: 20950
+author:
+type: other

changelogs/unreleased/fix-container-scanning-remediation-bug.yml

+---
+title: Fix bug in Container Scanning report remediations
+merge_request: 21980
+author:
+type: fixed

db/migrate/20191128145231_add_ci_resource_groups.rb

+# frozen_string_literal: true
+
+class AddCiResourceGroups < ActiveRecord::Migration[5.2]
+  DOWNTIME = false
+
+  def change
+    create_table :ci_resource_groups do |t|
+      t.timestamps_with_timezone
+      t.bigint :project_id, null: false
+      t.string :key, null: false, limit: 255
+      t.index %i[project_id key], unique: true
+    end
+
+    create_table :ci_resources do |t|
+      t.timestamps_with_timezone
+      t.references :resource_group, null: false, index: false, foreign_key: { to_table: :ci_resource_groups, on_delete: :cascade }
+      t.bigint :build_id, null: true
+      t.index %i[build_id]
+      t.index %i[resource_group_id build_id], unique: true
+    end
+  end
+end

db/migrate/20191128145232_add_fk_to_ci_resources_build_id.rb

+# frozen_string_literal: true
+
+class AddFkToCiResourcesBuildId < ActiveRecord::Migration[5.2]
+  include Gitlab::Database::MigrationHelpers
+
+  DOWNTIME = false
+
+  disable_ddl_transaction!
+
+  def up
+    add_concurrent_foreign_key :ci_resources, :ci_builds, column: :build_id, on_delete: :nullify
+  end
+
+  def down
+    remove_foreign_key_if_exists :ci_resources, column: :build_id
+  end
+end

db/migrate/20191128145233_add_fk_to_ci_resource_groups_project_id.rb

+# frozen_string_literal: true
+
+class AddFkToCiResourceGroupsProjectId < ActiveRecord::Migration[5.2]
+  include Gitlab::Database::MigrationHelpers
+
+  DOWNTIME = false
+
+  disable_ddl_transaction!
+
+  def up
+    add_concurrent_foreign_key :ci_resource_groups, :projects, column: :project_id, on_delete: :cascade
+  end
+
+  def down
+    remove_foreign_key_if_exists :ci_resource_groups, column: :project_id
+  end
+end

db/migrate/20191129144630_add_resource_group_id_to_ci_builds.rb

+# frozen_string_literal: true
+
+class AddResourceGroupIdToCiBuilds < ActiveRecord::Migration[5.2]
+  DOWNTIME = false
+
+  def up
+    unless column_exists?(:ci_builds, :resource_group_id)
+      add_column :ci_builds, :resource_group_id, :bigint
+    end
+
+    unless column_exists?(:ci_builds, :waiting_for_resource_at)
+      add_column :ci_builds, :waiting_for_resource_at, :datetime_with_timezone
+    end
+  end
+
+  def down
+    if column_exists?(:ci_builds, :resource_group_id)
+      remove_column :ci_builds, :resource_group_id, :bigint
+    end
+
+    if column_exists?(:ci_builds, :waiting_for_resource_at)
+      remove_column :ci_builds, :waiting_for_resource_at, :datetime_with_timezone
+    end
+  end
+end

db/migrate/20191129144631_add_index_to_resource_group_id.rb

+# frozen_string_literal: true
+
+class AddIndexToResourceGroupId < ActiveRecord::Migration[5.2]
+  include Gitlab::Database::MigrationHelpers
+
+  DOWNTIME = false
+  INDEX_NAME = 'index_for_resource_group'.freeze
+
+  disable_ddl_transaction!
+
+  def up
+    add_concurrent_index :ci_builds, %i[resource_group_id id], where: 'resource_group_id IS NOT NULL', name: INDEX_NAME
+    add_concurrent_foreign_key :ci_builds, :ci_resource_groups, column: :resource_group_id, on_delete: :nullify
+  end
+
+  def down
+    remove_foreign_key_if_exists :ci_builds, column: :resource_group_id
+    remove_concurrent_index_by_name :ci_builds, INDEX_NAME
+  end
+end

db/schema.rb

@@ -684,6 +684,8 @@ ActiveRecord::Schema.define(version: 2019_12_16_183532) do
     t.datetime_with_timezone "scheduled_at"
     t.string "token_encrypted"
     t.integer "upstream_pipeline_id"
+    t.bigint "resource_group_id"
+    t.datetime_with_timezone "waiting_for_resource_at"
     t.index ["artifacts_expire_at"], name: "index_ci_builds_on_artifacts_expire_at", where: "(artifacts_file <> ''::text)"
     t.index ["auto_canceled_by_id"], name: "index_ci_builds_on_auto_canceled_by_id"
     t.index ["commit_id", "artifacts_expire_at", "id"], name: "index_ci_builds_on_commit_id_and_artifacts_expireatandidpartial", where: "(((type)::text = 'Ci::Build'::text) AND ((retried = false) OR (retried IS NULL)) AND ((name)::text = ANY (ARRAY[('sast'::character varying)::text, ('dependency_scanning'::character varying)::text, ('sast:container'::character varying)::text, ('container_scanning'::character varying)::text, ('dast'::character varying)::text])))"
@@ -698,6 +700,7 @@ ActiveRecord::Schema.define(version: 2019_12_16_183532) do
     t.index ["project_id"], name: "index_ci_builds_on_project_id_for_successfull_pages_deploy", where: "(((type)::text = 'GenericCommitStatus'::text) AND ((stage)::text = 'deploy'::text) AND ((name)::text = 'pages:deploy'::text) AND ((status)::text = 'success'::text))"
     t.index ["protected"], name: "index_ci_builds_on_protected"
     t.index ["queued_at"], name: "index_ci_builds_on_queued_at"
+    t.index ["resource_group_id", "id"], name: "index_for_resource_group", where: "(resource_group_id IS NOT NULL)"
     t.index ["runner_id"], name: "index_ci_builds_on_runner_id"
     t.index ["scheduled_at"], name: "partial_index_ci_builds_on_scheduled_at_with_scheduled_jobs", where: "((scheduled_at IS NOT NULL) AND ((type)::text = 'Ci::Build'::text) AND ((status)::text = 'scheduled'::text))"
     t.index ["stage_id", "stage_idx"], name: "tmp_build_stage_position_index", where: "(stage_idx IS NOT NULL)"
@@ -872,6 +875,23 @@ ActiveRecord::Schema.define(version: 2019_12_16_183532) do
     t.index ["user_id"], name: "index_ci_pipelines_on_user_id"
   end
+  create_table "ci_resource_groups", force: :cascade do |t|
+    t.datetime_with_timezone "created_at", null: false
+    t.datetime_with_timezone "updated_at", null: false
+    t.bigint "project_id", null: false
+    t.string "key", limit: 255, null: false
+    t.index ["project_id", "key"], name: "index_ci_resource_groups_on_project_id_and_key", unique: true
+  end
+
+  create_table "ci_resources", force: :cascade do |t|
+    t.datetime_with_timezone "created_at", null: false
+    t.datetime_with_timezone "updated_at", null: false
+    t.bigint "resource_group_id", null: false
+    t.bigint "build_id"
+    t.index ["build_id"], name: "index_ci_resources_on_build_id"
+    t.index ["resource_group_id", "build_id"], name: "index_ci_resources_on_resource_group_id_and_build_id", unique: true
+  end
+
   create_table "ci_runner_namespaces", id: :serial, force: :cascade do |t|
     t.integer "runner_id"
     t.integer "namespace_id"
@@ -4395,6 +4415,7 @@ ActiveRecord::Schema.define(version: 2019_12_16_183532) do
   add_foreign_key "ci_builds", "ci_pipelines", column: "auto_canceled_by_id", name: "fk_a2141b1522", on_delete: :nullify
   add_foreign_key "ci_builds", "ci_pipelines", column: "commit_id", name: "fk_d3130c9a7f", on_delete: :cascade
   add_foreign_key "ci_builds", "ci_pipelines", column: "upstream_pipeline_id", name: "fk_87f4cefcda", on_delete: :cascade
+  add_foreign_key "ci_builds", "ci_resource_groups", column: "resource_group_id", name: "fk_6661f4f0e8", on_delete: :nullify
   add_foreign_key "ci_builds", "ci_stages", column: "stage_id", name: "fk_3a9eaa254d", on_delete: :cascade
   add_foreign_key "ci_builds", "projects", name: "fk_befce0568a", on_delete: :cascade
   add_foreign_key "ci_builds_metadata", "ci_builds", column: "build_id", on_delete: :cascade
@@ -4415,6 +4436,9 @@ ActiveRecord::Schema.define(version: 2019_12_16_183532) do
   add_foreign_key "ci_pipelines", "external_pull_requests", name: "fk_190998ef09", on_delete: :nullify
   add_foreign_key "ci_pipelines", "merge_requests", name: "fk_a23be95014", on_delete: :cascade
   add_foreign_key "ci_pipelines", "projects", name: "fk_86635dbd80", on_delete: :cascade
+  add_foreign_key "ci_resource_groups", "projects", name: "fk_774722d144", on_delete: :cascade
+  add_foreign_key "ci_resources", "ci_builds", column: "build_id", name: "fk_e169a8e3d5", on_delete: :nullify
+  add_foreign_key "ci_resources", "ci_resource_groups", column: "resource_group_id", on_delete: :cascade
   add_foreign_key "ci_runner_namespaces", "ci_runners", column: "runner_id", on_delete: :cascade
   add_foreign_key "ci_runner_namespaces", "namespaces", on_delete: :cascade
   add_foreign_key "ci_runner_projects", "projects", name: "fk_4478a6f1e4", on_delete: :cascade

doc/administration/incoming_email.md

@@ -7,7 +7,7 @@ GitLab has several features based on receiving incoming emails:
 - [New issue by email](../user/project/issues/managing_issues.md#new-issue-via-email):
   allow GitLab users to create a new issue by sending an email to a
   user-specific email address.
-- [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#create-new-merge-requests-by-email):
+- [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email-core-only):
   allow GitLab users to create a new merge request by sending an email to a
   user-specific email address.
 - [Service Desk](../user/project/service_desk.md): provide e-mail support to
@@ -79,7 +79,7 @@ email address in order to sign up.
 If you also host a public-facing GitLab instance at `hooli.com` and set your
 incoming email domain to `hooli.com`, an attacker could abuse the "Create new
 issue by email" or
-"[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#create-new-merge-requests-by-email)"
+"[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email-core-only)"
 features by using a project's unique address as the email when signing up for
 Slack, which would send a confirmation email, which would create a new issue or
 merge request on the project owned by the attacker, allowing them to click the

doc/administration/index.md

@@ -119,7 +119,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance. **(PREMIUM ONLY)**
 - [Incoming email](incoming_email.md): Configure incoming emails to allow
   users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/managing_issues.md#new-issue-via-email) and
-  [merge requests by email](../user/project/merge_requests/creating_merge_requests.md#create-new-merge-requests-by-email), and to enable [Service Desk](../user/project/service_desk.md).
+  [merge requests by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email-core-only), and to enable [Service Desk](../user/project/service_desk.md).
   - [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a
   basic Postfix mail server with IMAP authentication on Ubuntu for incoming
   emails.

doc/development/documentation/workflow.md

@@ -297,8 +297,7 @@ To request help:
 1. Locate the the Technical Writer for the relevant
    [DevOps stage group](https://about.gitlab.com/handbook/product/technical-writing/index.html#assignments).
 1. Either:
-   - If urgent help is required, directly assign the Technical Writer in the issue or
-     [in the merge request](../../user/project/merge_requests/creating_merge_requests.md#multiple-assignees-starter).
+   - If urgent help is required, directly assign the Technical Writer in the issue or in the merge request.
    - If non-urgent help is required, ping the Technical Writer in the issue or merge request.
 If you are a member of GitLab's Slack workspace, you can request help in `#docs`.

doc/gitlab-basics/add-merge-request.md

 ---
-type: howto
+redirect_to: '../user/project/merge_requests/creating_merge_requests.md'
 ---
-# How to create a merge request
-
-Merge requests are how you integrate separate changes that you've made in a
-[branch](create-branch.md) to a [project](create-project.md).
-
-This is a brief guide on how to create a merge request. For more detailed information,
-check the [merge requests documentation](../user/project/merge_requests/index.md), or
-you can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for
-a quick overview of working with merge requests.
-
-1. Before you start, you should have already [created a branch](create-branch.md)
-   and [pushed your changes](start-using-git.md#send-changes-to-gitlabcom) to GitLab.
-1. Go to the project where you'd like to merge your changes and click on the
-   **Merge requests** tab.
-1. Click on **New merge request** on the right side of the screen.
-1. From there, you have the option to select the source branch and the target
-   branch you'd like to compare to. The default target project is the upstream
-   repository, but you can choose to compare across any of its forks.
-
-   ![Select a branch](img/merge_request_select_branch.png)
-
-1. When ready, click on the **Compare branches and continue** button.
-1. At a minimum, add a title and a description to your merge request. Optionally,
-   select a user to review your merge request. You may also select a milestone and
-   labels.
-
-   ![New merge request page](img/merge_request_page.png)
-
-1. When ready, click on the **Submit merge request** button.
-
-Your merge request will be ready to be reviewed, approved, and merged.
-
-<!-- ## Troubleshooting
-
-Include any troubleshooting steps that you can foresee. If you know beforehand what issues
-one might have when setting this up, or when something is changed, or on upgrading, it's
-important to describe those, too. Think of things that may go wrong and include them here.
-This is important to minimize requests for support, and to avoid doc comments with
-questions that you know someone might ask.
-
-Each scenario can be a third-level heading, e.g. `### Getting error message X`.
-If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
+This document was moved to [another location](../user/project/merge_requests/creating_merge_requests.md).

doc/user/packages/conan_repository/index.md

@@ -22,46 +22,134 @@ by default. To enable it for existing projects, or if you want to disable it:
 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) with the scope set to `api` 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:
+## Getting started
+This section will cover installing Conan and building a package for your C/C++ project. This is a quickstart if you are 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).
+### Installing Conan
+
+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
+
+```sh
+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
+```sh
+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
+
+Understanding what is needed to create a valid and compilable C++ project is out of the scope of this guide, but if you are 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.
+Clone the repo 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:
+
+```sh
+conan new Hello/0.1 -t
+```
+
+Next, you will create a package for that recipe by running `conan create` providing the Conan user and channel:
+
+```sh
+conan create . my-org+my-group+my-project/beta
+```
+
+NOTE: **Note**
+Current [naming restrictions](#package-recipe-naming-convention) require you to name the `user` value as the `+` separated path of your project on GitLab.
+
+The example above would create a package belonging to this project: `https://gitlab.com/my-org/my-group/my-project` with a channel of `beta`.
+
+These two example commands will generate a final package with the recipe `Hello/0.1@my-org+my-group+my-project/beta`.
+
+For more advanced details on creating and managing your packages, refer to the [Conan docs](https://docs.conan.io/en/latest/creating_packages.html).
+
+You are now ready to upload your package to the GitLab registry. To get started, first you will need to set GitLab as a remote, then you will need to add a Conan user for that remote to authenticate your requests.
+
+## Adding the GitLab Package Registry as a Conan remote
+
+Add a new remote to your Conan configuration:
 ```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:
+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:
 ```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.
+## Authenticating to the GitLab Conan Repository
+You will need to generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication.
+### Adding a Conan user to the GitLab 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 do not have to explicitly add them to each Conan command you run:
+
+```sh
+conan user <gitlab-username> -r gitlab -p <personal_access_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 will automatically be included in the requests.
+
+Note: **Note**
+The personal access token is not stored locally at any moment. Conan uses JWT, so when you run this command, Conan will request an expirable token from GitLab using your token. The JWT does expire on a regular basis, so you will need to re-enter your personal access token when that happens.
+
+Alternatively, you could explicitly include your credentials in any given command.
+For example:
+
+```sh
+CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload Hello/0.1@my-group+my-project/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:
+
+```sh
+conan remote add_ref Hello/0.1@my-group+my-project/beta gitlab
+```
+
+NOTE: **Note**
+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 rest of the example commands in this documentation assume that you have added a Conan user with your credentials to the `gitlab` remote and will not include the explicit credentials or remote option, but be aware that any of the commands could be run without having added a user or default remote:
+
+```sh
+`CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> <conan command> --remote=gitlab
+```
 ## Uploading a package
@@ -72,14 +160,14 @@ Ensure you have a project created on GitLab and that the personal access token y
 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
+conan upload Hello/0.1@my-group+my-project/beta --all
 ```
 ### 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
+Standard Conan recipe convention looks like `package_name/version@user/channel`.
+**The recipe user 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:
@@ -95,7 +183,36 @@ A future iteration will extend support to [project and group level](https://gitl
 ## 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.
+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:
+
+```ini
+ [requires]
+ Hello/0.1@my-group+my-project/beta
+
+ [generators]
+ cmake
+```
+
+Next, from the root of your project, create a build directory and navigate to it:
+
+```sh
+mkdir build && cd build
+```
+
+Now you can install the dependencies listed in `conanfile.txt`:
+
+```sh
+conan install ..
+```
+
+NOTE: **Note:**
+If you are trying to install the package you just created in this tutorial, not much will happen since that package
+already exists on your local machine.
 ## Removing a package
@@ -104,8 +221,11 @@ 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
+  conan remove Hello/0.2@user/channel --remote=gitlab
   ```
+  
+  You need to explicitly include the remote in this command, otherwise the package will only be removed from your
+  local system cache.
   NOTE: **Note:**
   This command will remove all recipe and binary package files from the Package Registry.
@@ -119,9 +239,9 @@ The `conan search` command can be run searching by full or partial package name,
 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
+conan search Hello --all --remote=gitlab
+conan search He* --all --remote=gitlab
+conan search Hello/0.1@my-group+my-project/beta --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.
@@ -131,5 +251,15 @@ The scope of your search will include all projects you have permission to access
 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
+conan info Hello/0.1@my-group+my-project/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 info on a given package from the GitLab Package Registry.
+- `conan remove`: Delete the package from the GitLab Package Registry.

doc/user/packages/index.md

@@ -10,7 +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+ |
+| [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.6+ |
 | [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+ |
 | [NuGet Repository](https://gitlab.com/gitlab-org/gitlab/issues/20050) **(PREMIUM)**  | *COMING SOON* The GitLab NuGet Repository will enable every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.7 (planned) |