Add PushSecretName documentation

architecture/builds.adoc

@@ -44,3 +44,49 @@ STI builds are a replacement for the OpenShift v2-like developer experience. The
 == Custom Build
 Custom builds are the most sophisticated version of builds, allowing developers to define a builder image which is responsible for the entire process of the build. The custom builder image is a plain Docker image within which the author embeds the logic of the desired build process, such as building RPMs or building
 base Docker images.
+
+[#using-docker-credentials-for-pushing-images]
+== Using Docker credentials for pushing images
+
+In case you want to push the output image into private Docker Registry that
+requires authentication or Docker Hub, you have to supply the `.dockercfg` file
+with valid Docker Registry credentials.
+
+The `.dockercfg` JSON file usually exists in your home directory and it has following
+format:
+
+```
+{"https://index.docker.io/v1/":{"auth":"encrypted_password","email":"foo@bar.com"}}
+```
+
+You can also add authentication entries to this file by running `docker login`
+command. The file will be created if it does not exist.
+
+The 'https://index.docker.io/v1' is the URL of the registry. You can define
+multiple Docker registries entries in this file.
+
+Kubernetes provides the https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/secrets.md[Secret]
+resource, which you can use to store your passwords and configuration.
+In order to make Build use your `.dockercfg` file for pushing the output image,
+you have to create the Secret first. The 'data' field in Secret must contain the
+'dockercfg' key with the value set to base64 encoded content of the '.dockercfg'
+file. For example:
+
+```
+{
+  "apiVersion": "v1beta3",
+  "kind": "Secret",
+  "metadata": {
+    "name": "dockerhub"
+  },
+  "data": {
+    "dockercfg": "6yJodHRwc1ovL2zuZGV4LmRvY21lci5aby92MS8iOnsiYXV0aCI6ImJXWnZhblJwYXpwdVoybGxkR2d4TUE9PSIsImVtYWlsIj8ibWlAbWlmby5zayJ9fQ=="
+  }
+}
+
+```
+
+To create the secret, you can use 'osc create -f secret.json'. Once you have
+this secret created, you can add `PushSecretName` field into `Output` section
+inside the BuildConfig and set it to the name of the Secret that you created (in
+this case 'dockerhub').