anchor.diff:  
   // end::using-a-proxy-for-git-cloning-1[]
   
  -[[starting-a-build]]
  -
  -== Starting a Build
  -Manually invoke a build using the following command:
  -
  -----
  -$ oc start-build <BuildConfigName>
  -----
  -
  -Re-run a build using the `--from-build` flag:
  -
  -----
  -$ oc start-build --from-build=<build_name>
  -----
  -
  -Specify the `--follow` flag to stream the build's logs in stdout:
  -
  -----
  -$ oc start-build <BuildConfigName> --follow
  -----
  -
  -[[canceling-a-build]]
  -
  -== Canceling a Build
  -Manually cancel a build using the web console, or with the following CLI command:
  -
  -----
  -$ oc cancel-build <build_name>
  -----
  -
  -[[viewing-build-details]]
  -== Viewing Build Details
  -
  -You can view build details using the web console or the following CLI command:
  -
  -----
  -$ oc describe build <build_name>
  -----
  -
  -The output of the `describe` command includes details such as the build source,
  -strategy, and output destination. If the build uses the Docker or Source
  -strategy, it will also include information about the source revision used for
  -the build: commit ID, author, committer, and message.
  -
  -[[accessing-build-logs]]
  -
  -== Accessing Build Logs
  -You can access build logs using the web console or the CLI.
  -
  -To stream the logs using the build directly:
  -
  -----
  -$ oc logs -f build/<build_name>
  -----
  -
  -To stream the logs of the latest build for a build configuration:
  -
  -----
  -$ oc logs -f bc/<buildconfig_name>
  -----
  -
  -To return the logs of a given version build for a build configuration:
  -
  -----
  -$ oc logs --version=<number> bc/<buildconfig_name>
  -----
  -
  -*Log Verbosity*
  -
  -To enable more verbose output, pass the `*BUILD_LOGLEVEL*` environment variable
  -as part of the `*sourceStrategy*` or `*dockerStrategy*` in a `*BuildConfig*`:
  -
  -====
  -
  -----
  -{
  -  "sourceStrategy": {
  -    ...
  -    "env": [
  -      {
  -        "name": "BUILD_LOGLEVEL",
  -        "value": "2" <1>
  -      }
  -    ]
  -  }
  -}
  -----
  -
  -<1> Adjust this value to the desired log level.
  -====
  -
  -NOTE: A platform administrator can set verbosity for the entire OpenShift
  -instance by passing the `--loglevel` option to the `openshift start` command.
  -If both `--loglevel` and `BUILD_LOGLEVEL` are specified, `BUILD_LOGLEVEL` takes precedence.
  -
  -Available log levels for Source builds are as follows:
  -
  -[horizontal]
  -Level 0:: Produces output from containers running the *_assemble_* script and all encountered errors. This is the default.
  -Level 1:: Produces basic information about the executed process.
  -Level 2:: Produces very detailed information about the executed process.
  -Level 3:: Produces very detailed information about the executed process, and a listing of the archive contents.
  -Level 4:: Currently produces the same information as level 3.
  -Level 5:: Produces everything mentioned on previous levels and additionally provides docker push messages.
  -
  -[[source-code]]
  -
  -== Source Code
  -The source code location is one of the required parameters for the
  -`*BuildConfig*`. The build uses this location and fetches the source code that
  -is later built. The source code location definition is part of the
  -`*spec*` section in the `*BuildConfig*`:
  -
  -====
  -
  -----
  -{
  -  "source" : {
  -    "type" : "Git", <1>
  -    "git" : { <2>
  -      "uri": "git://github.com/openshift/ruby-hello-world.git"
  -    },
  -    "contextDir": "app/dir", <3>
  -  },
  -}
  -----
  -
  -<1> The `*type*` field describes which SCM is used to fetch your source code.
  -<2> The `*git*` field contains the URI to the remote Git repository of the
  -source code. Optionally, specify the `*ref*` field to check out a specific Git
  -reference. A valid `*ref*` can be a SHA1 tag or a branch name.
  -<3> The `*contextDir*` field allows you to override the default location inside
  -the source code repository where the build looks for the application source
  -code. If your application exists inside a sub-directory, you can override the
  -default location (the root folder) using this field.
  -====
  -
  -[[setting-maximum-duration]]
  -== Setting Maximum Duration
  -
  -When defining a `*BuildConfig*`, you can define its maximum duration by setting
  -the  `*completionDeadlineSeconds*` field. It is specified in seconds and is not
  -set by default. When not set, there is no maximum duration enforced.
  -
  -The maximum duration is counted from the time when a build pod gets scheduled in
  -the system, and defines how long it can be active, including the time needed to
  -pull the builder image. After reaching the specified timeout, the build is
  -terminated by OpenShift.
  -
  -The following example shows the part of a `*BuildConfig*` specifying
  -`*completionDeadlineSeconds*` field for 30 minutes:
  -
  -====
  -----
  -{
  -  "spec" : {
  -    "completionDeadlineSeconds" : 1800,
  -  }
  -}
  -----
  -====
  -
  -
  -[[build-triggers]]
  -
  -== Build Triggers
  -When defining a `*BuildConfig*`, you can define triggers to control the
  -circumstances in which the `*BuildConfig*` should be run. The following build
  -triggers are available:
  -
  -* link:#webhook-triggers[Webhook]
  -* link:#image-change-triggers[Image change]
  -* link:#config-change-triggers[Configuration change]
  -
  -[[webhook-triggers]]
  -
  -=== Webhook Triggers
  -Webhook triggers allow you to trigger a new build by sending a request to the
  -OpenShift API endpoint. You can define these triggers using
  -https://developer.github.com/webhooks/[GitHub webhooks] or Generic webhooks.
  -
  -*GitHub Webhooks*
  -
  -https://developer.github.com/webhooks/creating/[GitHub webhooks] handle the call
  -made by GitHub when a repository is updated. When defining the trigger, you must
  -specify a `*secret*`, which will be part of the URL you supply to GitHub when
  -configuring the webhook. The secret ensures the uniqueness of the URL, preventing
  -others from triggering the build. The following example is a trigger definition
  -JSON within the `*BuildConfig*`:
  -
  -====
  -
  -----
  -{
  -  "type": "GitHub",
  -  "github": {
  -    "secret": "secret101"
  -  }
  -}
  -----
  -====
  -
  -[NOTE]
  -====
  -The secret field in webhook trigger configuration is not the same as `*secret*`
  -field you encounter when configuring webhook in GitHub UI. The former is to make
  -the webhook URL unique and hard to predict, the latter is an optional string field
  -used to create HMAC hex digest of the body, which is sent as an `X-Hub-Signature`
  -https://developer.github.com/webhooks/#delivery-headers[header].
  -====
  -
  -The payload URL is returned as the GitHub Webhook URL by the `describe` command
  -(see link:#describe-buildconfig[below]), and is structured as follows:
  -
  -----
  -http://<openshift_api_host:port>/osapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github
  -----
  -
  -*Generic Webhooks*
  -
  -Generic webhooks can be invoked from any system capable of making a web
  -request. As with a GitHub webhook, you must specify a `*secret*` which will be
  -part of the URL, the caller must use to trigger the build. The secret ensures
  -the uniqueness of the URL, preventing others from triggering the build.
  -The following is an example trigger definition JSON within the `*BuildConfig*`:
  -
  -====
  -
  -----
  -{
  -  "type": "Generic",
  -  "generic": {
  -    "secret": "secret101"
  -  }
  -}
  -----
  -====
  -
  -To set up the caller, supply the calling system with the URL of the generic
  -webhook endpoint for your build:
  -
  -----
  -http://<openshift_api_host:port>/osapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic
  -----
  -
  -The endpoint can accept an optional payload with the following format:
  -
  -====
  -
  -----
  -{
  -  type: 'git',
  -  git: {
  -    uri: '<url to git repository>',
  -    ref: '<optional git reference>',
  -    commit: '<commit hash identifying a specific git commit>',
  -    author: {
  -      name: '<author name>',
  -      email: '<author e-mail>',
  -    },
  -    committer: {
  -      name: '<committer name>',
  -      email: '<committer e-mail>',
  -    },
  -    message: '<commit message>'
  -  }
  -}
  -----
  -====
  -
  -[[describe-buildconfig]]
  -
  -*Displaying a BuildConfig's Webhook URLs*
  -
  -Use the following command to display the webhook URLs associated with a build
  -configuration:
  -
  -----
  -$ oc describe bc <name>
  -----
  -
  -If the above command does not display any webhook URLs, then no webhook trigger
  -is defined for that build configuration.
  -
  -[[image-change-triggers]]
  -
  -=== Image Change Triggers
  -Image change triggers allow your build to be automatically invoked when a new
  -version of an upstream image is available. For example, if a build is based on
  -top of a RHEL image, then you can trigger that build to run any time the RHEL
  -image changes. As a result, the application image is always running on the
  -latest RHEL base image.
  -
  -Configuring an image change trigger requires the following actions:
  -
  -. Define an `*ImageStream*` that points to the upstream image you want to
  -trigger on:
  -+
  -====
  -
  -----
  -{
  -  "kind": "ImageStream",
  -  "apiVersion": "v1",
  -  "metadata": {
  -    "name": "ruby-20-centos7"
  -  }
  -}
  -----
  -====
  -+
  -This defines the image stream that is tied to a Docker image repository
  -located at `_<system-registry>_/_<namespace>_/ruby-20-centos7`. The
  -`_<system-registry>_` is defined as a service with the name `docker-registry`
  -running in OpenShift.
  -
  -. If an image stream is the base image for the build, set the from field in the
  -build strategy to point to the image stream:
  -+
  -====
  -
  -----
  -{
  -  "strategy": {
  -    "type": "Source",
  -    "sourceStrategy": {
  -      "from": {
  -        "kind": "ImageStreamTag",
  -        "name": "ruby-20-centos7:latest"
  -      },
  -    }
  -  }
  -}
  -----
  -====
  -+
  -In this case, the `*sourceStrategy*` definition is consuming the `latest` tag of
  -the image stream named `ruby-20-centos7` located within this namespace.
  -
  -. Define a build with one or more triggers that point to image streams:
  -+
  -====
  -
  -----
  -{
  -  "type": "imageChange", <1>
  -  "imageChange": {}
  -}
  -{
  -  "type": "imagechange", <2>
  -  "imageChange": {
  -     "from": {
  -       "kind": "ImageStreamTag",
  -       "name": "custom-image:latest"
  -     }
  -  }
  -}
  -----
  -
  -<1> An image change trigger that monitors the `*ImageStream*` and
  -`*Tag*` as defined by the build strategy's `*from*` field. The `*imageChange*` part
  -must be empty.
  -<2> An image change trigger that monitors an arbitrary image stream. The `*imageChange*`
  -part in this case must include a `*from*` field that references the `*ImageStreamTag*` to monitor.
  -====
  -
  -When using an image change trigger for the strategy image stream, the generated build
  -is supplied with an immutable Docker tag that points to the latest image corresponding
  -to that tag. This new image reference will be used by the strategy
  -when it executes for the build. For other image change triggers that do not
  -reference the strategy image stream, a new build will be started, but the build
  -strategy will not be updated with a unique image reference.
  -
  -In the example above that has an image change trigger for the strategy, the resulting build will be:
  -
  -====
  -
  -----
  -{
  -  "strategy": {
  -    "type": "Source",
  -    "sourceStrategy": {
  -      "from": {
  -        "kind": "DockerImage",
  -        "name": "172.30.17.3:5001/mynamespace/ruby-20-centos7:immutableid"
  -      }
  -    }
  -  }
  -}
  -----
  -====
  -
  -This ensures that the triggered build uses the new image that was just pushed to
  -the repository, and the build can be re-run any time with the same inputs.
  -
  -In addition to setting the image field for all `*Strategy*` types, for custom
  -builds, the `OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE` environment variable is checked.
  -If it does not exist, then it is created with the immutable image reference. If
  -it does exist then it is updated with the immutable image reference.
  -
  -If a build is triggered due to a webhook trigger or manual request,
  -the build that is created uses the `*immutableid*` resolved from the
  -`*ImageStream*` referenced by the `*Strategy*`. This ensures that builds
  -are performed using consistent image tags for ease of reproduction.
  -
  -[NOTE]
  -====
  -Image streams that point to Docker images in
  -http://docs.docker.com/v1.7/reference/api/hub_registry_spec/#docker-registry-1-0[v1
  -Docker registries] only trigger a build once when the image stream tag becomes
  -available and not on subsequent image updates. This is due to the lack of
  -uniquely identifiable images in v1 Docker registries.
  -====
  -
  -[[config-change-triggers]]
  -=== Configuration Change Triggers
  -A configuration change trigger allows a build to be automatically invoked as
  -soon as a new `*BuildConfig*` is created. The following is an example trigger
  -definition JSON within the `*BuildConfig*`:
  -
  -====
  -
  -----
  -{
  -  "type": "ConfigChange"
  -}
  -----
  -
  -====
  -
  -[NOTE]
  -====
  -Configuration change triggers currently only work when creating a new
  -`*BuildConfig*`. In a future release, configuration change triggers will also be
  -able to launch a build whenever a `*BuildConfig*` is updated.
  -====
  -
  -[#using-docker-credentials-for-pushing-and-pulling-images]
  -== Using Docker Credentials for Pushing and Pulling Images
  -
  -Supply the *_.dockercfg_* file with valid Docker Registry credentials in order to
  -push the output image into a private Docker Registry or pull the builder image
  -from the private Docker Registry that requires authentication. For the OpenShift
  -Docker Registry, you don't have to do this because `*secrets*` are generated
  -automatically for you by OpenShift.
  -
  -The *_.dockercfg_* JSON file is found in your home directory by default and has
  -the following format:
  -
  -====
  -
  -----
  -{
  -	"https://index.docker.io/v1/": { <1>
  -		"auth": "YWRfbGzhcGU6R2labnRib21ifTE=", <2>
  -		"email": "user@example.com" <3>
  -	}
  -}
  -----
  -
  -<1> URL of the registry.
  -<2> Encrypted password.
  -<3> Email address for the login.
  -====
  -
  -You can define multiple Docker registry entries in this file. Alternatively, you
  -can also add authentication entries to this file by running the `docker login`
  -command. The file will be created if it does not exist. Kubernetes provides
  -https://github.com/GoogleCloudPlatform/kubernetes/blob/master/docs/design/secrets.md[`*secret*`],
  -which are used to store your configuration and passwords.
  -
  -. Create the `*secret*` from your local *_.dockercfg_* file:
  -+
  -====
  -----
  -$ oc secrets new dockerhub ~/.dockercfg
  -----
  -====
  -+
  -This generates a JSON specification of the `*secret*` named *dockerhub* and
  -creates the object.
  -
  -. Once the `*secret*` is created, add it to the builder service account:
  -+
  -====
  -----
  -$ oc secrets add serviceaccount/builder secrets/dockerhub
  -----
  -====
  -
  -. Add a `*pushSecret*` field into the `*output*` section of the `*BuildConfig*` and
  -set it to the name of the `*secret*` that you created, which in the above example
  -is *dockerhub*:
  -+
  -====
  -
  -----
  -{
  -  "parameters": {
  -    "output": {
  -      "to": {
  -        "kind": "DockerImage"
  -        "name": "private.registry.com/org/private-image:latest"
  -      },
  -      "pushSecret":{
  -        "name": "dockerhub"
  -      }
  -    }
  -  }
  -}
  -----
  -====
  -
  -. Pull the builder Docker image from a private Docker registry by specifying the
  -`*pullSecret*` field, which is part of the build strategy definition:
  -+
  -====
  -
  -----
  -{
  -  "strategy": {
  -    "sourceStrategy": {
  -      "from": {
  -        "kind": "DockerImage",
  -        "name": "docker.io/user/private_repository"
  -       },
  -       "pullSecret": {
  -        "name": "dockerhub"
  -       },
  -    },
  -    "type": "Source"
  -  }
  -}
  -----
  -====
   
   [#using-private-repositories-for-builds]
  -== Using Private Repositories for Builds
  +=== Using Private Repositories for Builds
   
   Supply valid credentials to build an application from a private repository.
   
  
positive.code: 
  
  [[ssh-key-authentication]]
  === SSH Key Based Authentication
  
  SSH Key Based Authentication requires a private SSH key. A `.gitconfig` file can
  also be attached.
  
negative.code: and SSH key based authentication.
  
  [[basic-authentication]]
  ==== Basic Authentication
  
  Basic authentication requires either a combination of `username` and `password`,
  or a `token` to authenticate against the SCM server. A `CA certificate` file,
  