Input step

An input step is used to collect information from a user.

An input step is functionally identical to a block step, however an input step doesn't create any dependencies to the steps before and after it.

Input steps block your build from completing, but do not automatically block other steps from running unless they specifically depend upon it.

An input step can be defined in your pipeline settings, or in your pipeline.yml file.

pipeline.yml

steps:
  - input: "Information please"
    fields:
      - text: "What is the date today?"
        key: "todays-date"

You can add form fields to block steps by adding a fields attribute. Block steps with input fields can only be defined using a pipeline.yml. There are two field types available: text or select. The select input type displays differently depending on how you configure the options. If you allow people to select multiple options, they display as checkboxes. If you are required to select only one option from six or fewer, they display as radio buttons. Otherwise, the options display in a dropdown menu.

The data you collect from these fields is available to subsequent steps through the build meta-data command.

In this example, the pipeline.yml defines an input step with the key name. The Bash script then accesses the value of the step using the meta-data command.

pipeline.yml

  - input: "Who is running this script?"
    fields:
      - text: "Your name"
        key: "name"
  - label: "Run script"
    command: script.sh

script.sh

NAME=$(buildkite-agent meta-data get name)

For an example pipeline, see the Input step example pipeline on GitHub:

Input Step Example Pipeline github.com/buildkite/input-step-example

Don't store sensitive data in input steps

You shouldn't use input steps to store sensitive information like secrets because the data will be stored in build metadata.

Input step attributes

Input and block steps have the same attributes available for use.

Optional attributes:

`prompt`	The instructional message displayed in the dialog box when the 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 the step will be marked as passed. Available input field types: `text`, `select`
`branches`	The branch pattern defining which branches will include this input step in their builds. Example: `"main stable/*"`
`if`	A boolean expression to restrict the running of the step. See Using conditionals for supported expressions. Example: `build.message != "skip me"`
`depends_on`	A list of step keys that this step depends on. This step will only proceed after the named steps have completed. See managing step dependencies for more information. Example: `"test-suite"`
`key`	A unique string to identify the input step. Example: `"test-suite"`
`allow_dependency_failure`	Whether to continue to proceed past this step if any of the steps named in the `depends_on` attribute fail. Default: `false`

pipeline.yml

steps:
  - input: ":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 (using the buildkite-agent meta-data command)
The key may only contain alphanumeric characters, slashes, dashes, or underscores. Example: "release-name"

pipeline.yml

steps:
  - input: "Release information"
    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"`

pipeline.yml

steps:
  - input: "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 (using the buildkite-agent meta-data command) The key may only contain alphanumeric characters, slashes, dashes, or underscores. 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. If selecting multiple options is permitted the options will be displayed as checkboxes.

Each select option has the following required attributes:

`label`	The text displayed for the option. Example: `"Stable"`
`value`	The value to be stored as meta-data (to be later retrieved using the buildkite-agent meta-data command) Example: `"stable"`

pipeline.yml

steps:
  - input: "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. When this value is set to `false` and users can only select one option, the options display in a dropdown menu, regardless of how many options there are. Default: `true`
`multiple`	A boolean value that defines whether multiple options may be selected. When multiple options are selected, they are delimited in the meta-data field by a line break (`\n`) Default: `false`
`default`	The value of the option or options that will be pre-selected. When `multiple` is enabled, this can be an array of values to select by default. Example: `"beta"`

pipeline.yml

steps:
  - input: "Release details"
    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"

Input validation

To prevent users from entering invalid text values in input steps (for example, to gather some deployment information), you can use input validation.

If you associate a regular expression to a field, the field outline will turn red when an invalid value is entered.

To do it, use the following sample syntax:

steps:
  - input: "Click me!"
    fields:
      - text: Must be hexadecimal
        key: hex
        format: "[0-9a-f]+"

The format must be a regular expression implicitly anchored to the beginning and end of the input and is functionally equivalent to the HTML5 pattern attribute.