docs: URL parameter for configuring remotes

modules/end-user-guide/nav.adoc

@@ -14,6 +14,7 @@
 *** xref:url-parameter-for-the-devfile-file-name.adoc[]
 *** xref:url-parameter-for-the-devfile-file-path.adoc[]
 *** xref:url-parameter-for-the-workspace-storage.adoc[]
+*** xref:url-parameter-for-configuring-project-remotes.adoc[]
 ** xref:basic-actions-you-can-perform-on-a-workspace.adoc[]
 ** xref:authenticating-to-a-git-server-from-a-workspace.adoc[]
 * xref:customizing-workspace-components.adoc[]

modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc

@@ -15,3 +15,4 @@ When you start a new workspace, {prod-short} configures the workspace according
 * xref:url-parameter-for-the-devfile-file-name.adoc[]
 * xref:url-parameter-for-the-devfile-file-path.adoc[]
 * xref:url-parameter-for-the-workspace-storage.adoc[]
+* xref:url-parameter-for-configuring-project-remotes.adoc[]

modules/end-user-guide/pages/url-parameter-for-configuring-project-remotes.adoc

@@ -0,0 +1,49 @@
+:_content-type: CONCEPT
+:description: URL parameter for configuring project remotes
+:keywords: configuring-remotes, configuring-remotes-parameter, remotes-parameter, project-remotes-parameter
+:navtitle: URL parameter for configuring project remotes
+:page-aliases:
+
+[id="url-parameter-for-configuring-project-remotes"]
+= URL parameter for configuring project remotes
+
+When you open a URL to start a new workspace, the origin remote will be configured automatically. Additional Git remotes can be configured on the command line after workspace startup, or by editing the {devworkspace} {orch-name} resource for the new workspace after its creation. 
+
+To have {prod-short} automatically configure Git remotes on workspace creation, the `remotes=<remotes>` URL parameter can be used.
+
+The first remote specified in the `remotes` parameter will have its default branch checked out on workspace startup.
+
+The value of the `remotes` parameter can be provided in two formats: by providing both remote names and URLs, or by providing only URLs.
+
+== Providing remote names and URLs
+
+Remote names and URLs can be specified by providing a list of `{name,URL}` pairs in the following format:
+
+[source,subs="+quotes,+attributes,+macros"]
+----
+{{origin,https://git-url/origin/project.git},{upstream,https://git-url/upstream/project.git}, ... }
+----
+
+The following example configures two remotes on workspace creation, `origin` and `upstream`. The `origin` remote's default branch is checked out on workspace startup.
+[source,subs="+quotes,+attributes,+macros"]
+----
+pass:c,a,q[{prod-url}]#__<git_repository_url>__?remotes={{origin,https://git-url/origin/project.git},{upstream,https://git-url/upstream/project.git}}
+----
+
+== Providing only URLs
+
+Remote URLs can be specified by providing a list of URLs in the following format:
+
+[source,subs="+quotes,+attributes,+macros"]
+----
+{https://git-url/origin/project.git,https://git-url/upstream/project.git, ... }
+----
+
+When remotes are configured in this format, the remote names are implicit. 
+The first remote is `origin`, the second remote is `upstream`, and subsequent remotes are `fork1`, `fork2`, ... ,  `fork(n-2)`.
+
+The following example configures three remotes on workspace creation, `origin`, `upstream`, and `fork1`. The `origin` remote's default branch is checked out on workspace startup.
+[source,subs="+quotes,+attributes,+macros"]
+----
+pass:c,a,q[{prod-url}]#__<git_repository_url>__?remotes={https://git-url/origin/project.git,https://git-url/upstream/project.git,https://git-url/user/project.git} <1>
+----