Build Steps

Contract

LambdaCD build steps are regular clojure functions that fulfil a lightweight contract:

• They must take two arguments, args and ctx
• They must return a map with at least the key :status set.

This makes the following the minimal correct LambdaCD build step:

(defn some-step [args ctx]
  {:status :success})

Input

args

The first argument taken by any LambdaCD build step is used to share data between build steps. It contains the output of the previous build-step plus, potentially, global values under the :global key.

Container-Steps like with-git might also use args to communicate information to their children (e.g. the :revision in the case of with-git). Details on this can be found in the documentation of the respective container steps.

ctx

The second argument taken by any LambdaCD build step is used to access the LambdaCD context it is running in and provides meta-information about the current step and data to access LambdaCD APIs.

See Build Context for details.

Output

Every LambdaCD build step must return a map that contains the output of the step that will be passed on to the next step as args. This can be arbitrary data but a few keys have special meaning or are manditory:

• :status (mandatory): Communicates the steps state. Can be :success, :failure, :waiting (only makes sense while a step is running) or :killed. Pipeline Steps need to be successful for the pipeline to continue. Missing or other :status values will be treated as a failure of the step.

• :out (optional): The console output of this step that will be displayed in the UI

• :global (optional): Value must be a map. All key-value-pairs in this map will be provided to all subsequent steps under the :global-key of args. If more than one step returns global values, those will be merged. Global values can be helpful for information that is relevant for all steps in the pipeline, e.g. the version of artifacts built early in the pipeline

• :details: This is interpreted by the UI to provide human readable informations about the build step and it's result, such as links to artifacts that were produced, informations on test runs and so on. It's an array of maps with three keys:

  • :label: A text to be displayed
  • :href: (optional): A URL to the text points to
  • :raw: (optional): Preformatted text, e.g. code or stack traces (supported since 0.7.1)
  • :details: (optional): Another set of details nested underneath this detail

  Example:

  {:status  :success
     :details [{:label   "Some Links"
                :details [{:label "Builds API"
                           :href  "/api/builds/"}
                          {:label "Github"
                           :href  "https://github.com/flosell/lambdacd"}]}
               {:label   "Mock test results"
                :details [{:label "Unit Tests: 0/10 failed"}
                          {:label   "Integration Tests Tests: 1/5 failed"
                           :details [{:label "SomeTestClass.shouldBeFailingWhenTested"
                                      :raw   "java.lang.AssertionError: expected:<0> but was:<10>\n\tat org.junit.Assert.fail(Assert.java:88)\n\tat org.junit.Assert.failNotEquals(Assert.java:743)\n\tat org.junit.Assert.assertEquals(Assert.java:118)"}]}]}]}