Build Steps

Contract

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

• They must take two arguments, ctx and args
• 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 [ctx args]
  {:status :success})

Input

ctx

The first 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.

args

The second 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.

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 mandatory:

• :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)"}]}]}]}

  

Metadata

Build Steps can declare metadata to inform LambdaCD how it should treat them:

(defn ^{:display-type :parallel} some-container-step [^:hide arg & children]
  (do-something))

Metadata on Steps:

• :display-type: Declares how a build step (especially container steps) are displayed in the UI
  • :step: Normal build step (default for normal build steps)
  • :container: children will be displayed sequentially (default for container steps)
  • :parallel: children will be displayed to indicate they run in parallel
• :depends-on-previous-steps: setting this indicates that this step can not be retriggered because it needs previous steps to run first (e.g. when steps share a workspace and a step consumes an artifact created in this workspace by a previous step)

Metadata on Arguments:

• :hide: Hides the argument in the UI