♟️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	- &select-example label: Select field type: select name: TEST_SELECT_FIELD defaultValue: One availableValues: - One - Two - Three
Remote Select*	secure mandatory note readonly availableValues url path	- &remote-select-example label: Remote select field type: remote_select name: TEST_REMOTE_SELECT_FIELD availableValues: url: "https://hub.docker.com/v2/repositories/atlassian/jira-software/tags/?page=1&page_size=100&name=8" path: "$.results.[*].name"
Text	secure mandatory note readonly defaultValue regex hidden	- &text-example label: Text field type: text name: TEST_TEXT_FIELD defaultValue: I am a test regex: .*
Textarea	secure mandatory note readonly defaultValue regex hidden	- &textarea-example label: Text Area name: TEXT_AREA_FIELD type: textarea defaultValue: | Line1 Line2 regex: .*
Number	secure mandatory note readonly defaultValue regex	- &number-example label: Number type: number name: number defaultValue: 24 regex: .*
Checkbox (single select)	secure mandatory note readonly defaultValue true | false	- &checkbox-example label: Checkbox field type: checkbox name: TEST_CHECKBOX_FIELD defaultValue: true
Checkbox group (multi-select)	secure mandatory note readonly availableValues	- &checkbox-group-example label: Checkbox group type: checkbox_group name: TEST_CHECKBOX_GROUP availableValues: - First - Second - Third
Radio button	secure mandatory note readonly defaultValue availableValues	- &radio-field-example label: Radio field type: radio name: TEST_RADIO_FIELD mandatory: true defaultValue: One availableValues: - One - Two - Three
Date	secure mandatory note readonly defaultValue Format: yyyy-mm-dd	- &date-example label: Date field type: date name: TEST_DATE_FIELD defaultValue: 2023-05-06

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.

fields:
  - &example-text-field
    label: Text field
    type: text
    name: EXAMPLE_TEXT_FIELD
    defaultValue: I am a test
    mandatory: true
    regex: .*
  - &example-select-field
    label: Select field
    type: select
    name: EXAMPLE_SELECT_FIELD
    note: "Select any value from below list"
    defaultValue: Select 1
    availableValues:
      - Select 1
      - Select 2
      - Select 3
  - &example-radio-field
    label: Radio field
    type: radio
    name: EXAMPLE_RADIO_FIELD
    availableValues:
      - Radio 1
      - Radio 2
forms:
  - name: Small form with radio
    fields:
      - *example-text-field
      - *example-radio-field
    pipeline: test
    groups:
      - TEST_GROUP
      - JIRA
  - name: Small form with select
    fields:
      - *example-text-field
      - *example-select-field
    groups:
      - JIRA
    pipeline: test
  - name: Big form without group
    fields:
      - *example-text-field
      - *example-radio-field
      - *example-select-field
    pipeline: test2

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.

fields:
  - &example-text-field
    label: Text field
    type: text
    name: EXAMPLE_TEXT_FIELD
    defaultValue: I am a test
    mandatory: true
    regex: .*
  - &example-select-field
    label: Select field
    type: select
    name: EXAMPLE_SELECT_FIELD
    note: "Select any value from below list"
    defaultValue: Select 1
    availableValues:
      - Select 1
      - Select 2
      - Select 3
  - &example-radio-field
    label: Radio field
    type: radio
    name: EXAMPLE_RADIO_FIELD
    availableValues:
      - Radio 1
      - Radio 2
forms:
  - name: Small form with radio
    fields:
      - *example-text-field
      - *example-radio-field
    pipeline: test
    groups:
      - TEST_GROUP
      - JIRA
  - name: Small form with select
    fields:
      - *example-text-field
      - *example-select-field
    groups:
      - JIRA
    pipeline: test
  - name: Big form without group
    fields:
      - *example-text-field
      - <<: *example-text-field
        defaultValues: Text field value
        readonly: true
      - *example-radio-field
      - *example-select-field
    pipeline: test2