Issue and Pull Request Templates

Some projects have a standard list of questions that users need to answer when creating an issue or pull request. Gitea supports adding templates to the main branch of the repository so that they can autopopulate the form when users are creating issues and pull requests. This will cut down on the initial back and forth of getting some clarifying details.

Additionally, the New Issue page URL can be suffixed with ?title=Issue+Title&body=Issue+Text and the form will be populated with those strings. Those strings will be used instead of the template if there is one.

File names

Possible file names for issue templates:

  • ISSUE_TEMPLATE.md
  • ISSUE_TEMPLATE.yaml
  • ISSUE_TEMPLATE.yml
  • issue_template.md
  • issue_template.yaml
  • issue_template.yml
  • .gitea/ISSUE_TEMPLATE.md
  • .gitea/ISSUE_TEMPLATE.yaml
  • .gitea/ISSUE_TEMPLATE.yml
  • .gitea/issue_template.md
  • .gitea/issue_template.yaml
  • .gitea/issue_template.yml
  • .github/ISSUE_TEMPLATE.md
  • .github/ISSUE_TEMPLATE.yaml
  • .github/ISSUE_TEMPLATE.yml
  • .github/issue_template.md
  • .github/issue_template.yaml
  • .github/issue_template.yml

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

Directory names

Alternatively, users can create multiple issue templates inside a special directory and allow users to choose one that more specifically addresses their problem.

Possible directory names for issue templates:

  • ISSUE_TEMPLATE
  • issue_template
  • .gitea/ISSUE_TEMPLATE
  • .gitea/issue_template
  • .github/ISSUE_TEMPLATE
  • .github/issue_template
  • .gitlab/ISSUE_TEMPLATE
  • .gitlab/issue_template

Inside the directory can be multiple markdown (.md) or yaml (.yaml/.yml) issue templates of the form.

Syntax for markdown template

  1. ---
  3. name: "Template Name"
  4. about: "This template is for testing!"
  5. title: "[TEST] "
  6. ref: "main"
  7. labels:
  9. - bug
  10. - "help needed"
  12. ---
  14. This is the template!

In the above example, when a user is presented with the list of issues they can submit, this would show as Template Name with the description This template is for testing!. When submitting an issue with the above example, the issue title would be pre-populated with [TEST] while the issue body would be pre-populated with This is the template!. The issue would also be assigned two labels, bug and help needed, and the issue will have a reference to main.

Syntax for yaml template

This example YAML configuration file defines an issue form using several inputs to report a bug.

  1. name: Bug Report
  2. about: File a bug report
  3. title: "[Bug]: "
  4. body:
  5.   - type: markdown
  6.     attributes:
  7.       value: |
  8.         Thanks for taking the time to fill out this bug report!
  9.   - type: input
  10.     id: contact
  11.     attributes:
  12.       label: Contact Details
  13.       description: How can we get in touch with you if we need more info?
  14.       placeholder: ex. email@example.com
  15.     validations:
  16.       required: false
  17.   - type: textarea
  18.     id: what-happened
  19.     attributes:
  20.       label: What happened?
  21.       description: Also tell us, what did you expect to happen?
  22.       placeholder: Tell us what you see!
  23.       value: "A bug happened!"
  24.     validations:
  25.       required: true
  26.   - type: dropdown
  27.     id: version
  28.     attributes:
  29.       label: Version
  30.       description: What version of our software are you running?
  31.       options:
  32.         - 1.0.2 (Default)
  33.         - 1.0.3 (Edge)
  34.     validations:
  35.       required: true
  36.   - type: dropdown
  37.     id: browsers
  38.     attributes:
  39.       label: What browsers are you seeing the problem on?
  40.       multiple: true
  41.       options:
  42.         - Firefox
  43.         - Chrome
  44.         - Safari
  45.         - Microsoft Edge
  46.   - type: textarea
  47.     id: logs
  48.     attributes:
  49.       label: Relevant log output
  50.       description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
  51.       render: shell
  52.   - type: checkboxes
  53.     id: terms
  54.     attributes:
  55.       label: Code of Conduct
  56.       description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
  57.       options:
  58.         - label: I agree to follow this project's Code of Conduct
  59.           required: true

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:

KeyDescriptionRequiredTypeDefaultValid values
valueThe text that is rendered. Markdown formatting is supported.RequiredString--

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:

KeyDescriptionRequiredTypeDefaultValid values
labelA brief description of the expected user input, which is also displayed in the form.RequiredString--
descriptionA description of the text area to provide context or guidance, which is displayed in the form.OptionalStringEmpty String-
placeholderA semi-opaque placeholder that renders in the text area when empty.OptionalStringEmpty String-
valueText that is pre-filled in the text area.OptionalString--
renderIf 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.OptionalString-Languages known to Gitea.

Validations:

KeyDescriptionRequiredTypeDefaultValid values
requiredPrevents form submission until element is completed.OptionalBooleanfalse-

Input

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

Attributes:

KeyDescriptionRequiredTypeDefaultValid values
labelA brief description of the expected user input, which is also displayed in the form.RequiredString--
descriptionA description of the field to provide context or guidance, which is displayed in the form.OptionalStringEmpty String-
placeholderA semi-transparent placeholder that renders in the field when empty.OptionalStringEmpty String-
valueText that is pre-filled in the field.OptionalString--

Validations:

KeyDescriptionRequiredTypeDefaultValid values
requiredPrevents form submission until element is completed.OptionalBooleanfalse-
is_numberPrevents form submission until element is filled with a number.OptionalBooleanfalse-
regexPrevents form submission until element is filled with a value that match the regular expression.OptionalString-a regular expression

Dropdown

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

Attributes:

KeyDescriptionRequiredTypeDefaultValid values
labelA brief description of the expected user input, which is displayed in the form.RequiredString--
descriptionA description of the dropdown to provide extra context or guidance, which is displayed in the form.OptionalStringEmpty String-
multipleDetermines if the user can select more than one option.OptionalBooleanfalse-
optionsAn array of options the user can choose from. Cannot be empty and all choices must be distinct.RequiredString array--

Validations:

KeyDescriptionRequiredTypeDefaultValid values
requiredPrevents form submission until element is completed.OptionalBooleanfalse-

Checkboxes

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

Attributes:

KeyDescriptionRequiredTypeDefaultValid values
labelA brief description of the expected user input, which is displayed in the form.RequiredString--
descriptionA description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting.OptionalStringEmpty String-
optionsAn array of checkboxes that the user can select. For syntax, see below.RequiredArray--

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

KeyDescriptionRequiredTypeDefaultOptions
labelThe identifier for the option, which is displayed in the form. Markdown is supported for bold or italic text formatting, and hyperlinks.RequiredString--
requiredPrevents form submission until element is completed.OptionalBooleanfalse-