Note: GitHub's form schema is currently in beta and subject to change.
About GitHub's form schema
You can use GitHub's form schema to configure forms for supported features. For more information, see "Configuring issue templates for your repository."
A form is a set of elements for requesting user input. You can configure a form by creating a YAML form definition, which is an array of form elements. Each form element is a set of key-value pairs that determine the type of the element, the properties of the element, and the constraints you want to apply to the element. For some keys, the value is another set of key-value pairs.
For example, the following form definition includes four form elements: a text area for providing the user's operating system, a dropdown menu for choosing the software version the user is running, a checkbox to acknowledge the Code of Conduct, and Markdown that thanks the user for completing the form.
- type: textarea
attributes:
label: Operating System
description: What operating system are you using?
placeholder: Example: macOS Big Sur
value: operating system
validations:
required: true
- type: dropdown
attributes:
label: Version
description: What version of our software are you running?
multiple: false
options:
- label: 1.0.2 (Default)
- label: 1.0.3 (Edge)
validations:
required: true
- type: checkboxes
attributes:
label: Code of Conduct
description: The Code of Conduct helps create a safe space for everyone. We require
that everyone agrees to it.
options:
- label: I agree to follow this project's [Code of Conduct](link/to/coc)
required: true
- type: markdown
attributes:
value: "Thanks for completing our form!"
Keys
For each form element, you can set the following keys.
Key | Description | Required | Type | Default | Valid values |
---|---|---|---|---|---|
type | The type of element that you want to define. | Required | String |
| |
id | The identifier for the element, except when type is set to markdown . Só é possível usar caracteres alfanuméricos, - e _ . Deve ser único na definição da forma. If provided, the id is the canonical identifier for the field in URL query parameter prefills. | Optional | String | ||
attributes | A set of key-value pairs that define the properties of the element. | Required | Hash | ||
validations | A set of key-value pairs that set constraints on the element. | Optional | Hash |
You can choose from the following types of form elements. Each type has unique attributes and validations.
Type | Description |
---|---|
markdown | Markdown text that is displayed in the form to provide extra context to the user, but is not submitted. |
textarea | A multi-line text field. |
input | A single-line text field. |
dropdown | A dropdown menu. |
checkboxes | A set of checkboxes. |
markdown
You can use a markdown
element to display Markdown in your form that provides extra context to the user, but is not submitted.
Attributes
Para o valor da chave atributos
, você pode definir as seguintes chaves.
Key | Description | Required | Type | Default | Valid values |
---|---|---|---|---|---|
value | The text that is rendered. Markdown formatting is supported. | Required | String |
Tips: YAML processing will treat the hash symbol as a comment. To insert Markdown headers, wrap your text in quotes.
For multi-line text, you can use the pipe operator.
Example
body:
- type: markdown
attributes:
value: "## Thank you for contributing to our project!"
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report.
textarea
You can use a textarea
element to add a multi-line text field to your form. Contributors can also attach files in textarea
fields.
Attributes
Para o valor da chave atributos
, você pode definir as seguintes chaves.
Key | Description | Required | Type | Default | Valid values |
---|---|---|---|---|---|
label | A brief description of the expected user input, which is also displayed in the form. | Required | String | ||
description | A description of the text area to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | |
placeholder | A semi-opaque placeholder that renders in the text area when empty. | Optional | String | Empty String | |
value | Text that is pre-filled in the text area. | Optional | String | ||
render | If a value is provided, submitted text will be formatted into a codeblock. When this key is provided, the text area will not expand for file attachments or Markdown editing. | Optional | String | Languages known to GitHub. For more information, see the languages YAML file. |
Validations
Para o valor da chave validações
, você pode definir as seguintes chaves.
Key | Description | Required | Type | Default | Valid values |
---|---|---|---|---|---|
required | evita o envio do formulário até que o elemento seja concluído. | Optional | Boolean | false |
Example
body:
- type: textarea
id: repro
attributes:
label: Reproduction steps
description: "How do you trigger this bug? Please walk us through it step by step."
value: |
1.
2.
3.
...
render: bash
validations:
required: true
input
You can use an input
element to add a single-line text field to your form.
Attributes
Para o valor da chave atributos
, você pode definir as seguintes chaves.
Key | Description | Required | Type | Default | Valid values |
---|---|---|---|---|---|
label | A brief description of the expected user input, which is also displayed in the form. | Required | String | ||
description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | |
placeholder | A semi-transparent placeholder that renders in the field when empty. | Optional | String | Empty String | |
value | Text that is pre-filled in the field. | Optional | String |
Validations
Para o valor da chave validações
, você pode definir as seguintes chaves.
Key | Description | Required | Type | Default | Valid values |
---|---|---|---|---|---|
required | evita o envio do formulário até que o elemento seja concluído. | Optional | Boolean | false |
Example
body:
- type: input
id: prevalence
attributes:
label: Bug prevalence
description: "How often do you or others encounter this bug?"
placeholder: "Example: Whenever I visit the personal account page (1-2 times a week)"
validations:
required: true
dropdown
You can use a dropdown
element to add a dropdown menu in your form.
Attributes
Para o valor da chave atributos
, você pode definir as seguintes chaves.
Key | Description | Required | Type | Default | Valid values |
---|---|---|---|---|---|
label | A brief description of the expected user input, which is displayed in the form. | Required | String | ||
description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String | Empty String | |
multiple | Determines if the user can select more than one option. | Optional | Boolean | false | |
options | An array of options the user can choose from. Cannot be empty and all choices must be distinct. | Required | String array |
Validations
Para o valor da chave validações
, você pode definir as seguintes chaves.
Key | Description | Required | Type | Default | Valid values |
---|---|---|---|---|---|
required | evita o envio do formulário até que o elemento seja concluído. | Optional | Boolean | false |
Example
body:
- type: dropdown
id: download
attributes:
label: How did you download the software?
options:
- Homebrew
- MacPorts
- apt-get
- Built from source
validations:
required: true
checkboxes
You can use the checkboxes
element to add a set of checkboxes to your form.
Attributes
Para o valor da chave atributos
, você pode definir as seguintes chaves.
Key | Description | Required | Type | Default | Valid values |
---|---|---|---|---|---|
label | A brief description of the expected user input, which is displayed in the form. | Required | String | ||
description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | |
options | An array of checkboxes that the user can select. For syntax, see below. | Required | Array |
Para cada valor na matriz de opções
, você pode definir as seguintes chaves.
Tecla | Descrição | Obrigatório | Tipo | Padrão | Opções |
---|---|---|---|---|---|
etiqueta | O identificador da opção, que é exibido no formulário. O Markdown é compatível com a formatação de texto em negrito ou itálico e hiperlinks. | Obrigatório | string | ||
required | evita o envio do formulário até que o elemento seja concluído. | Optional | Boolean | false |
Example
body:
- type: checkboxes
id: operating-systems
attributes:
label: Which operating systems have you used?
description: You may select more than one.
options:
- label: macOS
- label: Windows
- label: Linux