anchor.diff:  and SSH key based authentication.
   
   [[basic-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,
  
positive.code: 
  // 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
  
  Supply valid credentials to build an application from a private repository.
  
  
negative.code: $ oc secrets add serviceaccount/builder secrets/mysecret
  ----
  ====
  
  
  [[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.
  
  [[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"
    }
  }
  ----
  ====
  
  
  [[build-output]]
  == Build Output
  