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 input steps by adding a fields attribute. 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 users to select multiple options, those options display as checkboxes. If users are required to select only one option from six or fewer, those options display as radio buttons. Seven or more options display as 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 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`
`allowed_teams`	A list of teams that are permitted to complete this step, whose values are a list of one or more team slugs or IDs. If this field is specified, a user must be a member of one of the teams listed in order to submit a value to complete this step. The use of `allowed_teams` replaces the need for write access to the pipeline, meaning a member of an allowed team with read-only access may complete the step. Learn more about this attribute in the Permissions section. Example: `["deployers", "approvers", "b50084ea-4ed1-405e-a204-58bde987f52b"]`
`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"`
`blocked_state`	The state that the build is set to when the build is blocked by this block step. If you're using GitHub, you can also configure which GitHub status to use for blocked builds on a per-pipeline basis. Default: `passed` Values: `passed`, `failed`, `running`
`key`	A unique string to identify the input step. Keys cannot have the same pattern as a UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). Example: `"test-suite"` Alias: `identifier`
`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 field 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:

`text`	The text input name. Example: `"Release Name"`
`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"`
`format`	A regular expression used for input validation that indicates invalid input. Example: `"[a-zA-Z]+"`

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 field 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 six or fewer 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.

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: "Deploy To"
    fields:
      - select: "Regions"
        key: "deploy-regions"
        hint: "Which regions should we deploy this to? :earth_asia:"
        required: true
        multiple: true
        default:
          - "na"
          - "eur"
          - "asia"
          - "aunz"
        options:
          - label: "North America"
            value: "na"
          - label: "Europe"
            value: "eur"
          - label: "Asia"
            value: "asia"
          - label: "Oceania"
            value: "aunz"

Each select option has the following required attributes:

`label`	Descriptive 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"`

Permissions

To complete an input step, a user must either have write access to the pipeline, or where the allowed_teams attribute is specified, the user must belong to one of the allowed teams. When allowed_teams is specified, a user who has write access to the pipeline but is not a member of any of the allowed teams will not be permitted to complete the step.

The allowed_teams attribute serves as a useful way to restrict input permissions to a subset of users without restricting the ability to create builds. Conversely, this attribute is also useful for granting input permissions to users without also granting the ability create builds.

pipeline.yml

- input: "Release"
  prompt: "Fill out the details for release"
  allowed_teams:
    - "approvers"
  fields:
    - text: "Release Name"
      key: "release-name"

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.