♟️Syntax for the pipeline-forms.yml file

How to create valid and meaningful forms for your pipelines

Extend the built-in Pipeline feature with PFO fields in 3 steps:

  1. Create fields

  2. Add fields to forms

  3. Connect forms with pipelines

4. (Optional) - Group fields into presets - prefill fields and create variations

5. (Optional) - Validate form before a commit - with the online validator

Creating fields

Fields and forms can be added by editing the pipeline-forms.yml,which is a custom file you have to create in addition to having thebitbucket-pipelines.yml.

This is a basic example for creating a text and a select field with some options. 

fields:
  - &example-text-field
    label: Text field
    type: text
    name: TEST_TEXT_FIELD
    defaultValue: I am a test
  - &mandatory-text-field
    <<: *example-text-field
    mandatory: true
  - &example-select-field
    label: Select field
    type: select
    name: TEST_SELECT_FIELD
    note: "Select any value from below list"
    defaultValue: One
    availableValues:
      - One
      - Two
      - Three

You can also use the characters '<<:' to add more values to previously defined fields.

Available attributes

Keys and values can be selected from the following set:

Key
Value
Usage

label*

display name for the field

Will be visible on the form.

type*

expected field type

Will determine field type and options.

name*

The value can be referred from the configuration as an ID.

note

description for the fields

Will be visible under the field as a helper text.

defaultValue

predefined value

The value will be added by default on the form.

mandatory

true value makes the field required

The field can not be empty when submitting.

availableValues**

can be added at fields with a fix set of values

When values can be selected from a strict list.

secure

true value makes the field hidden

Password and other secret values that should not be shared (even viewed) after inserting.

hidden

true value makes the field not showing on the form

Make a field prefilled in the background, without the possibility to change the value. Like a hard coded variable.

readonly

true value makes the field visible on the form, but default value can not be overwritten

Make a field prefilled, but show on the form to let the user know. This is useful while using presets, to fill and protect several fields in advance.

regex

a regular expression pattern to validate the input value

Use this property to enforce a specific format or pattern for user input. The input value must match the provided regular expression for successful validation.

* = required

**= required where aplicable

Available field types

In PFO you can extend your pipelines with the following field types while editing the pipeline-forms.yml:

Field Type
Available modifiers
Example snippet

Select

  • secure

  • mandatory

  • note

  • readonly

  • defaultValue

  • availableValues

Remote Select*

with Variables

  • secure

  • mandatory

  • note

  • readonly

  • availableValues

    • url

    • path

    • headers (optional)

    • method (optional, default: GET)

    • body (optional)

Text

  • secure

  • mandatory

  • note

  • readonly

  • defaultValue

  • regex

  • hidden

Textarea

  • secure

  • mandatory

  • note

  • readonly

  • defaultValue

  • regex

  • hidden

Number

  • secure

  • mandatory

  • note

  • readonly

  • defaultValue

  • regex

Checkbox (single select)

  • secure

  • mandatory

  • note

  • readonly

  • defaultValue

    • true | false

Checkbox group (multi-select)

  • secure

  • mandatory

  • note

  • readonly

  • availableValues

Radio button

  • secure

  • mandatory

  • note

  • readonly

  • defaultValue

  • availableValues

Date

  • secure

  • mandatory

  • note

  • readonly

  • defaultValue

    • Format: yyyy-mm-dd

When adding a field right at the forms you don't need to use the anchor.

*When using remote select, the specified URL must point to a publicly accessible endpoint which must give a JSON formatted response body. The path must be specified as a JSON Path, which you can experiment with using the https://jsonpath.com/ tool.

Building forms

Fields need to be added to the pipeline-forms.yml first, then they can be added to forms. Forms will be rendered on the UI when selected.

Presets (Groups)

If you want a field or form similar to an existing one but with different default values you don't have to copy the whole object, just use the power of YAML Anchors. This way you can reference an existing object and override only some of its properties.

PreviousCreate FormsNextVariables

Last updated