# Create Forms

## Before setting up the first Form

{% hint style="info" %}
Your **custom forms** for the **Pipline Forms** app are **stored in your repository**, under the file named **`pipeline-forms.yml`** - which **you have to create**. `pipeline-forms.yml` should be on the root level, just next to the`bitbucket-pipelines.yml`file. New to Bitbucket Pipelines? Get started [here](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/)!
{% endhint %}

<figure><img src="/files/AllwbVxHJPcjPaZK12LA" alt=""><figcaption><p>The user created pipeline-forms.yml</p></figcaption></figure>

This means that the file (all your forms) is **version controlled by you**, and any changes on the branches should be merged back to the main/master branch to be availabe - just as it works in `bitbicket-pipelines.yml`.

This also means that the`pipeline-forms.yml` file **may vary branch-by-branch**, which could lead to different options in your forms on different branches.

After creating a `pipeline-forms.yml` you can edit it with your expected forms then commit to make it visible on the UI.

## Creating a form

{% hint style="info" %}
**Prerequisite**: Make sure you have a pipeline in the `bitbucket-pipelines.yml`which contains a custom pipeline, called "**Demonstration pipeline**". Otherwise you have to change that value in the upcoming example for an existing pipeline to select.
{% endhint %}

The `pipeline-forms.yml` can consist of the following configuration elements:

* **groups** - ability to group forms into presets
* **fields** - different type of input fields, may contain options
* **forms** - can be displyed to gather input data
  * linked to a pipeline
  * fields can be added on the forms

{% hint style="info" %}
To show a form on the UI, you should add  at least one valid form with a field on it.
{% endhint %}

Edit your `pipeline-forms.yml` with

* 1 group
* 2 simple fields&#x20;
* a form (using the 2 fields)&#x20;
* link the form with the "test" pipeline
* link the form with the group

{% code title="pipeline-forms.yml" %}

```yaml
groups:
  - label: Important Forms
    key: IMFO
fields:
  - &test-text-field  
    label: Text field
    type: text
    name: TEST_TEXT_FIELD
    note: This will appear as a description under the field
    defaultValue: I am a test
    mandatory: true
  - &test-select-field
    label: Select field
    type: select
    name: TEST_SELECT_FIELD
    defaultValue: One
    availableValues:
      - One
      - Two
      - Three
forms:
  - name: Test Jira form
    fields:
      - *test-text-field
      - *test-select-field
    pipeline: Demonstration pipeline
    groups:
      - IMFO
```

{% endcode %}

{% hint style="info" %}
PFO is currently parsing **custom pipelines** only, so make sure that you are using a custom pipeline.
{% endhint %}

The form will appear on the **Pipeline Forms** menu, when the proper branch and commit is selected.

<figure><img src="/files/w6hgJV1LbV4hiFuDJD5Z" alt=""><figcaption><p>New form is ready to use - when the proper commit is selected</p></figcaption></figure>

{% hint style="success" %}
To implement advanced forms, check out the [Syntax for the pipeline-forms.yml file](/pipeline-forms/user-guides/user-guide/create-forms/syntax-for-the-pipeline-forms.yml-file.md) page!
{% endhint %}

## Editing forms

Forms should be edited by editing the `pipeline-forms.yml` which is a user craeted file in your repository's root.

You can use your favourite source code editor, or simply use the Bitbucket UI code editor.

## Adding a new form

When you have a form, just repeat the process and add another form in the same and only `pipeline-forms.yml`.

## Validating forms

If you are unsure if your form has a valid syntax use the **Validate** option on the right top by copy-pasting your form's content in the editor:

<figure><img src="/files/2syicjGoZnEg9Yl6wXUr" alt=""><figcaption><p>Validating forms directly on the UI</p></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.meta-inf.hu/pipeline-forms/user-guides/user-guide/create-forms.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.