File: docs\user\issue-pull-request-templates.md

---
title: 'Issue and Pull Request Templates'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/issue-pull-request-templates.en-us.md'
---

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`
- `docs`

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

```md
---
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.

```yaml
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:

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

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](https://en.wikipedia.org/wiki/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. For syntax, see below.                               | 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 issue only, or both. Valid options are "form" and "content".        | Optional | String array | false   | -       |

visible: Default is **[form, content]**

## Syntax for issue config

This is an example for an issue config file

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

### Possible Options

| Key                  | Description                                           | Type               | Default     |
| -------------------- | ----------------------------------------------------- | ------------------ | ----------- |
| blank_issues_enabled | If set to false, the user is forced to use a template | Boolean            | true        |
| contact_links        | Custom links to show in the choose box                | Contact Link Array | Empty Array |

### Contact Link

| Key   | Description                      | Type   | Required |
| ----- | -------------------------------- | ------ | -------- |
| name  | the name of your link            | String | true     |
| url   | The URL of your link             | String | true     |
| about | A short description of your link | String | true     |