Card origin_devexp_286 - Added ssh key-based access to private git repository documentation

architecture/core_objects/builds.adoc

@@ -115,6 +115,7 @@ following format:
 		"auth": "YWRfbGzhcGU6R2labnRib21ifTE=", <2>
 		"email": "[email protected]" <3>
 	}
+}
 ----
 
 <1> URL of the registry.
@@ -164,3 +165,113 @@ $ osc create -f secret.json
 Once you have the `*Secret*` created, you can add a `PushSecretName` field into
 `Output` section inside the `BuildConfig` and set it to the name of the
 `*Secret*` that you created, in this case `*dockerhub*`.
+
+[#using-private-repositories-for-builds]
+== Using private repositories for builds
+
+If you want to build your application from a private repository you must
+supply valid credentials. Currently only SSH key based authentication is supported.
+The keys used to access that repository live in `$HOME/.ssh/` directory.
+They are usually named `id_dsa.pub`, `id_ecdsa.pub`, `id_ed25519.pub` or `id_rsa.pub`.
+If you don't have any, you can generate them with the following command:
+
+====
+
+----
+$ ssh-keygen -t rsa -C "[email protected]"
+----
+====
+
+Once that's done you're going to get two files: one containing your public key (as
+explained above) and one containing a corresponding private key (one of `id_dsa`, `id_ecdsa`,
+`id_ed25519` or `id_rsa`). With both of these in place you should consult your
+source control management (SCM) system's manual on how to upload the public key.
+The private one will be used to access your private repository.
+
+Kubernetes provides the
+https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/secrets.md[Secret]
+resource, which you can use to store your keys. You must create the `*Secret*` first
+before builds can use your ssh key for accessing your private repository.
+The `*data*` field for the `*Secret*` object must contain your private key
+with the value set to the base64-encoded content of that file. For example:
+
+====
+
+----
+$ base64 -w 0 $HOME/.ssh/id_rsa
+6yJodHRwc1ovL2zuZGV4LmRvY21lci5aby92MS8iOnsiYXV0aCI6ImJXWnZhblJwYXpwdVoybGxkR2d4TUE9PSIsImVtYWlsIj8ibWlAbWlmby5zayJ9fQ==
+----
+====
+
+Copy the value returned from `base64` command and paste it into `ssh-privatekey` field
+in `*_secret.json_*` file:
+
+====
+
+----
+{
+  "apiVersion": "v1beta3",
+  "kind": "Secret",
+  "metadata": {
+    "name": "scmsecret"
+  },
+  "data": {
+    "ssh-privatekey": "6yJodHRwc1ovL2zuZGV4LmRvY21lci5aby92MS8iOnsiYXV0aCI6ImJXWnZhblJwYXpwdVoybGxkR2d4TUE9PSIsImVtYWlsIj8ibWlAbWlmby5zayJ9fQ=="
+  }
+}
+
+----
+====
+
+You can then create the `*Secret*` from the *_secret.json_* file using the following command:
+
+====
+
+----
+$ osc create -f secret.json
+----
+====
+
+Once you have the `*Secret*` created, you can add a `SourceSecretName` field into
+`Source` section inside the `BuildConfig` and set it to the name of the
+`*Secret*` that you created, in this case `*scmsecret*`:
+
+====
+
+----
+{
+  "apiVersion": "v1beta3",
+  "kind": "BuildConfig",
+  "metadata": {
+    "name": "sample-build",
+  },
+  "parameters": {
+    "output": {
+      "to": {
+        "name": "sample-image"
+      }
+    },
+    "source": {
+      "git": {
+        "uri": "[email protected]:user/app.git"
+      },
+      "sourceSecretName": "scmsecret",
+      "type": "Git"
+    },
+    "strategy": {
+      "stiStrategy": {
+        "from": {
+          "kind": "ImageStreamTag",
+          "name": "python-33-centos7:latest"
+        }
+      },
+      "type": "STI"
+    }
+  }
+----
+====
+
+[NOTE]
+====
+The URL of private repository is usually in the form `[email protected]:username/repository`
+====