Block Step

A block step is used to pause the execution of a build and wait on a team member to unblock it via the web or the API.

A basic block step can be defined in your pipeline settings, or in your pipeline.yml file. Once all steps before the block have completed, the pipeline will pause and wait for a team member to unblock it. Clicking on a block step in the Buildkite web UI opens a dialog box asking if you'd like to continue.

Screenshot of a basic block step

You can add form fields to block steps with the fields attribute. The data you collect from these fields is then available to subsequent steps in the pipeline in the build meta-data. Block steps with input fields can only be defined using a pipeline.yml.

Screenshot of a block step with input fields

For a complete example pipeline, including dynamically generated input fields, see the Block Step Example Pipeline on GitHub:

:pipeline: Block Step Example Pipelinegithub.com/buildkite/block-step-example

Block Step Attributes

Optional attributes:

prompt The instructional message displayed in the dialog box when the unblock step is activated.
Example: "Release to production?"
Example: "Fill out the details for this release"
fields A list of input fields required to be filled out before unblocking the step.
Available input field types: text, select
branches The branch pattern defining which branches will include this block step in their builds.
Example: "master stable/*"
steps:
  - block: ":rocket: Release!"

Text Input Attributes

Line endings

A text field normalizes line endings to Unix format (\n).

Required attributes:

key The meta-data key that stores the field's input (e.g. via the buildkite-agent meta-data command)
The key may only contain alphanumeric characters, slashes or dashes. Example: "release-name"
steps:
  - block: "Request Release"
    fields: 
      - text: "Code Name"
        key: "release-name"

Optional attributes:

hint The explanatory text that is shown after the label.
Example: "What’s the code name for this release? :name_badge:"
required A boolean value that defines whether the field is required for form submission.
Default value: true
default The value that is pre-filled in the text field.
Example: "Flying Dolphin"
steps:
  - block: "Request Release"
    fields: 
      - text: "Code Name"
        key: "release-name"
        hint: "What’s the code name for this release? :name_badge:"
        required: false
        default: "Release #"

Select Input Attributes

Required attributes:

key The meta-data key that stores the field's input (e.g. via the buildkite-agent meta-data command)
The key may only contain alphanumeric characters, slashes or dashes. Example: "release-stream"
options The list of select field options. For 6 or less options they’ll be displayed as radio buttons, otherwise they'll be displayed in a dropdown box.

Each select option has the following required attributes:

label The text displayed on the select list item.
Example: "Stable"
value The value to be stored as meta-data (e.g. to be later retreived via the buildkite-agent meta-data command)
Example: "stable"
steps:
  - block: "Request Release"
    fields: 
      - select: "Stream"
        key: "release-stream"
        options:
          - label: "Beta"
            value: "beta"
          - label: "Stable"
            value: "stable"

Optional attributes:

hint The text displayed directly under the select field’s label.
Example: "Which release stream does this belong in? :fork:"
required A boolean value that defines whether the field is required for form submission.
Default: true
default The value of the option that will be pre-selected in the dropdown.
Example: "beta"
steps:
  - block: "Request Release"
    fields: 
      - select: "Stream"
        key: "release-stream"
        hint: "Which release stream does this belong in? :fork:"
        required: false
        default: "beta"
        options:
          - label: "Beta"
            value: "beta"
          - label: "Stable"
            value: "stable"