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. There are two field types available: text or select. The select input type is displayed as radio buttons when it contains less than six items, and as a drop down list when it contains more than six items.

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"