fix: change git credential mounting docs to be devworkspace-specific (#…

…2275)

Co-authored-by: Max Leonov <[email protected]>
Co-authored-by: Fabrice Flore-Thébault <[email protected]>

modules/end-user-guide/pages/git-credential-store.adoc

@@ -1,25 +1,87 @@
-:navtitle: Git credential store
+:navtitle: Creating a {orch-name} Secret for a Git credentials store
 :keywords: user-guide, configuring, user, secrets
 :page-aliases: 
 
-[id="mounting-a-git-credential-store-into-a-workspace-container_{context}"]
-= Mounting a Git credentials store into a workspace container
+[id="mounting-a-git-credential-store-into-workspace-containers_{context}"]
+= Creating a {orch-name} Secret for a Git credentials store
 
-This section describes how to mount Git credentials store as secret from the user's {orch-namespace} into the file in single-workspace or multiple-workspace containers of {prod-short}.
+As an alternative to the OAuth for GitHub, GitLab, or Bitbucket that is configured by the administrator of your organization's {prod-short} instance, you can apply your Git credentials store as a Secret in your user {orch-namespace}.
+
+When mounting the Secret, a Git configuration file with the path to the mounted Git credentials store is automatically configured and mounted to the {devworkspace} containers at `/etc/gitconfig`.
 
 .Prerequisites
 
 * A running instance of {prod-short}.
+* You have CLI or GUI access to the {orch-name} cluster of your organization's {prod-short} instance.
+* For CLI users: The `{orch-cli}` and link:https://www.gnu.org/software/coreutils/base64[`base64`] command line tools are installed in the operating system you are using.
 
 .Procedure
-. Prepare Git credential file in the link:https://git-scm.com/docs/git-credential-store#_storage_format[Storage format].
-. Encode content of the file to the base64 format.
-. Create a new {platforms-name} secret in the {platforms-name} {orch-namespace} where a {prod-short} workspace will be created.
+. In your home directory, locate and open your `.git-credentials` file if you already have it. Alternatively, if you do not have this file, save a new `.git-credentials` file, using the link:https://git-scm.com/docs/git-credential-store#_storage_format[Git credentials storage format]. Each credential is stored on its own line in the file:
+
++
+[subs="+quotes,+attributes,+macros"]
+----
+https://__<username>__:__<token>__@__<git_server_hostname>__
+----
+
++
+.A line in a `.git-credentials` file
+====
+`https://trailblazer:[email protected]`
+====
+
+. Select credentials from your `.git-credentials` file for the Secret. Encode the selected credentials to Base64 for the next step.
++
+[TIP]
+====
+CLI users can use the `base64` command as needed:
+
+* To encode all lines in the file:
++
+`$ cat .git-credentials | base64 | tr -d '\n'`
+
+* To encode a selected line:
++
+`$ echo -n '__<copied_and_pasted_line_from_.git-credentials>__' | base64`
+====
+
+. Create a new {orch-name} Secret in your user {orch-namespace}.
++
+[source,yaml,subs="+quotes,+attributes,+macros"]
+----
+apiVersion: v1
+kind: Secret
+metadata:
+  name: git-credentials-secret
+  labels:
+    controller.devfile.io/git-credential: 'true' <1>
+    controller.devfile.io/watch-secret: 'true'
+  annotations:
+    controller.devfile.io/mount-path: /etc/secret <2>
+data:
+  credentials: __<Base64_content_of_.git-credentials>__ <3>
+----
++
+<1> The `controller.devfile.io/git-credential` label marks the Secret as containing Git credentials.
+<2> A custom absolute path in the {devworkspace} containers. The Secret is mounted as the `credentials` file at this path. The default path is `/`.
+<3> The selected content from `.git-credentials` that you encoded to Base64 in the previous step.
++
+[TIP]
+====
+You can create and apply multiple Git credentials Secrets in your user {orch-namespace}. All of them will be copied into one Secret that will be mounted to the {devworkspace} containers. For example, if you set the mount path to `/etc/secret`, then the one Secret with all of your Git credentials will be mounted at `/etc/secret/credentials`. You must set all Git credentials Secrets in your user {orch-namespace} to the same mount path. You can set the mount path to an arbitrary path because the mount path will be automatically set in the Git configuration file configured at `/etc/gitconfig`.
+====
 
-* The labels of the secret that is about to be created must match the set of labels configured in `che.workspace.provision.secret.labels` property of {prod-short}. The default labels are:
+. Use the CLI or GUI to apply the Secret to the {orch-name} cluster of your organization's {prod-short} instance.
 
-* `app.kubernetes.io/part-of: che.eclipse.org` 
-* `app.kubernetes.io/component: workspace-secret`:
 +
-include::example$snip_{project-context}-git-credential-file-as-kubernetes-secret-into-the-file.adoc[leveloffset=+1]
+[TIP]
+====
+CLI users can apply the Secret with `{orch-cli}`:
 
+[subs="+quotes,+attributes,+macros"]
+----
+$ {orch-cli} apply -f - <<EOF
+__<Secret_prepared_in_the_previous_step>__
+EOF
+----
+====