anchor.diff:  $ 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
  
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: ----
  ====
  
  [[source-code]]
  
  == Git Repository Source Options
  
  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.
  ====
  
  [[using-a-proxy-for-git-cloning]]
  
  === Using a Proxy for Git Cloning
  
  // tag::using-a-proxy-for-git-cloning-1[]
  
  