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. Forgejo supports adding templates to the default 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. It is currently not possible to provide generic issue/pull-request templates globally. In general, there is the choice of using either multiple or a single issue template file(s), a single pull-request template file and additionally the possibility of adding an issue config.

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.

Directory names

Users can create multiple template files inside a special directory and this allows different use cases: users can choose to use the template that is suited to address their specific problem. Please note that there can be multiple issue templates. However, there may only be a single pull request template in one repository.

Forgejo will check for template files in the following directories, since Forgejo checks these services to make migration from them easier:

  • .forgejo
  • .gitea
  • .github
  • .gitlab

Inside the directory can be multiple markdown (.md) or yaml (.yaml/.yml) files for templates of the form - these are the three allowed file extensions.

File names

For the three file types - issue templates, pull request templates, and issue configs, there are various possible file names that may be used in the directories listed above.

Issue templates are arbitrarily named files with any of the three file extensions mentioned above, and there may be any number of them, so they each get their dedicated subdirectory: issue_template and ISSUE_TEMPLATE are the possible names for the subdirectory that the issue templates go into.

In contrast, there may only be a single pull request template per repository, so there is no extra subdirectory for it. It can reside in any of the .<service_name> directories (with the exception of the .gitlab directory, this is not supported!) listed in the previous section. A pull request template has a fixed name (see options below) and can end with any of the three file extensions mentioned above.

Possible file names and file extensions 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

Issue config template files need to go into the same subdirectory as issue template files (see above section). Possible file names and file extensions for issue config:

  • config.yaml
  • config.yml

An example setup for a single issue template file together with a single pull request template file could look like this:

.forgejo/
  ISSUE_TEMPLATE/
    issue_template.yaml
  pull_request_template.yml

Another example setup but with multiple issue template files instead could look like this:

.forgejo/
  issue_template/
    bug.yaml
    config.yml
    feature.yaml
  pull_request_template.md

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!

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.

name: Bug Report
about: File a bug report
title: '[Bug]: '
ref: 'main'
labels:
  - bug
  - 'help needed'
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 issue has been created
  - type: markdown
    attributes:
      value: |
        This issue was created by an issue **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 issue, 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 issue 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:

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

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:

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 Forgejo.

Validations:

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

visible: Default is [form, content]

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

visible: Default is [form, content]

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-

visible: Default is [form, content]

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-
visibleWhether a specific checkbox appears in the form only, in the created issue only, or both. Valid options are “form” and “content”.OptionalString arrayfalse-

visible: Default is [form, content]

Syntax for issue config

This is an example for an issue config file

blank_issues_enabled: true
contact_links:
  - name: Forgejo
    url: https://forgejo.org/
    about: Visit the Forgejo Website

Possible Options

KeyDescriptionTypeDefault
blank_issues_enabledIf set to false, the user is forced to use a templateBooleantrue
contact_linksCustom links to show in the choose boxContact Link ArrayEmpty Array
KeyDescriptionTypeRequired
namethe name of your linkStringtrue
urlThe URL of your linkStringtrue
aboutA short description of your linkStringtrue