Pull Request Templates

Some projects have a standard list of questions that users need to answer when creating pull request. DevOps Control supports adding templates to the default branch of the repository so that they can autopopulate the form when users are creating pull requests. This will cut down on the initial back and forth of getting some clarifying details. It is currently not possible to provide generic pull-request templates globally.

File names

Possible file names for PR templates:

PULL_REQUEST_TEMPLATE.md
PULL_REQUEST_TEMPLATE.yaml
PULL_REQUEST_TEMPLATE.yml
pull_request_template.md
pull_request_template.yaml
pull_request_template.yml
.gitea/PULL_REQUEST_TEMPLATE.md
.gitea/PULL_REQUEST_TEMPLATE.yaml
.gitea/PULL_REQUEST_TEMPLATE.yml
.gitea/pull_request_template.md
.gitea/pull_request_template.yaml
.gitea/pull_request_template.yml
.github/PULL_REQUEST_TEMPLATE.md
.github/PULL_REQUEST_TEMPLATE.yaml
.github/PULL_REQUEST_TEMPLATE.yml
.github/pull_request_template.md
.github/pull_request_template.yaml
.github/pull_request_template.yml

Syntax for markdown template

---

name: "Template Name"
about: "This template is for testing!"
title: "[TEST] "
ref: "main"
labels:

- bug
- "help needed"

---

This is the template!

When submitting pull request with the preceding example, the pull request title would be pre-populated with [TEST] while the pull request body would be pre-populated with This is the template!. The pull request would also be assigned two labels, bug and help needed, and the pull request will have a reference to main.

Syntax for yaml template

This example YAML configuration file defines pull request form using several inputs to report a bug.

name: Bug Report
about: File a bug report
title: "[Bug]: "
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!
  # some markdown that will only be visible once the pull request has been created
  - type: markdown
    attributes:
      value: |
        This pull request was created by an pull request **template** :)
    visible: [content]
  - type: input
    id: contact
    attributes:
      label: Contact Details
      description: How can we get in touch with you if we need more info?
      placeholder: ex. email@example.com
    validations:
      required: false
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Also tell us, what did you expect to happen?
      placeholder: Tell us what you see!
      value: "A bug happened!"
    validations:
      required: true
  - type: dropdown
    id: version
    attributes:
      label: Version
      description: What version of our software are you running?
      options:
        - 1.0.2 (Default)
        - 1.0.3 (Edge)
    validations:
      required: true
  - type: dropdown
    id: browsers
    attributes:
      label: What browsers are you seeing the problem on?
      multiple: true
      options:
        - Firefox
        - Chrome
        - Safari
        - Microsoft Edge
  - type: textarea
    id: logs
    attributes:
      label: Relevant log output
      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
      render: shell
  - type: checkboxes
    id: terms
    attributes:
      label: Code of Conduct
      description: By submitting this pull request, you agree to follow our [Code of Conduct](https://example.com)
      options:
        - label: I agree to follow this project's Code of Conduct
          required: true
        - label: I have also read the CONTRIBUTION.MD
          required: true
          visible: [form]
        - label: This is a TODO only visible after pull request creation
          visible: [content]

Markdown

You can use a markdown element to display Markdown in your form that provides extra context to the user, but is not submitted by default.

Attributes:


Key	Description	Required	Type	Default	Valid values
value	The text that is rendered. Markdown formatting is supported.	Required	String	-	-

visible: Default is form

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:


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 DevOps Control.

Validations:


Key	Description	Required	Type	Default	Valid values
required	Prevents form submission until element is completed.	Optional	Boolean	false	-

visible: Default is form, content

Input

You can use an input element to add a single-line text field to your form.

Attributes:


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:


Key	Description	Required	Type	Default	Valid values
required	Prevents form submission until element is completed.	Optional	Boolean	false	-
is_number	Prevents form submission until element is filled with a number.	Optional	Boolean	false	-
regex	Prevents form submission until element is filled with a value that match the regular expression.	Optional	String	-	a regular expression

visible: Default is form, content

Dropdown

You can use a dropdown element to add a dropdown menu in your form.

Attributes:


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:


Key	Description	Required	Type	Default	Valid values
required	Prevents form submission until element is completed.	Optional	Boolean	false	-

visible: Default is form, content

Checkboxes

You can use the checkboxes element to add a set of checkboxes to your form.

Attributes:


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.	Required	Array	-	-

For each value in the options array, you can set the following keys.


Key	Description	Required	Type	Default	Options
label	The identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks.	Required	String	-	-
required	Prevents form submission until element is completed.	Optional	Boolean	false	-
visible	Whether a specific checkbox appears in the form only, in the created pull request only, or both. Valid options are "form" and "content".	Optional	String array	false	-

visible: Default is form, content