2023-03-07 05:06:35 -05:00
---
2023-03-07 05:10:27 -05:00
title: 'Issue and Pull Request Templates'
license: 'Apache-2.0'
2024-04-21 09:56:01 -04:00
origin_url: 'https://github.com/go-gitea/gitea/blob/e865de1e9d65dc09797d165a51c8e705d2a86030/docs/content/usage/issue-pull-request-templates.en-us.md'
2023-03-07 05:06:35 -05:00
---
Some projects have a standard list of questions that users need to answer
2023-03-07 05:10:27 -05:00
when creating an issue or pull request. Forgejo supports adding templates to the
2024-02-24 15:20:29 -05:00
**default branch of the repository** so that they can autopopulate the form when users are
2023-03-07 05:06:35 -05:00
creating issues and pull requests. This will cut down on the initial back and forth
of getting some clarifying details.
2024-04-21 09:56:01 -04:00
It is currently not possible to provide generic issue/pull-request templates globally.
2023-03-07 05:06:35 -05:00
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`
2023-04-28 11:44:45 -04:00
Possible file names for issue config:
- `.gitea/ISSUE_TEMPLATE/config.yaml`
- `.gitea/ISSUE_TEMPLATE/config.yml`
- `.gitea/issue_template/config.yaml`
- `.gitea/issue_template/config.yml`
- `.github/ISSUE_TEMPLATE/config.yaml`
- `.github/ISSUE_TEMPLATE/config.yml`
- `.github/issue_template/config.yaml`
- `.github/issue_template/config.yml`
2023-03-07 05:06:35 -05:00
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
```md
---
2023-03-31 16:57:57 -04:00
name: 'Template Name'
about: 'This template is for testing!'
title: '[TEST] '
ref: 'main'
2023-03-07 05:06:35 -05:00
labels:
2023-03-31 16:57:57 -04:00
- bug
- 'help needed'
2023-03-07 05:06:35 -05:00
---
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
2023-03-31 16:57:57 -04:00
title: '[Bug]: '
2023-03-07 05:06:35 -05:00
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report!
2024-04-21 09:56:01 -04:00
# 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]
2023-03-07 05:06:35 -05:00
- 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!
2023-03-31 16:57:57 -04:00
value: 'A bug happened!'
2023-03-07 05:06:35 -05:00
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
2024-04-21 09:56:01 -04:00
- label: I have also read the CONTRIBUTION.MD
required: true
visible: [form]
- label: This is a TODO only visible after issue creation
visible: [content]
2023-03-07 05:06:35 -05:00
```
### Markdown
2024-04-21 09:56:01 -04:00
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.
2023-03-07 05:06:35 -05:00
Attributes:
| Key | Description | Required | Type | Default | Valid values |
2023-03-31 16:57:57 -04:00
| ----- | ------------------------------------------------------------ | -------- | ------ | ------- | ------------ |
2023-03-07 05:06:35 -05:00
| value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - |
2024-04-21 09:56:01 -04:00
visible: Default is ** [form]**
2023-03-07 05:06:35 -05:00
### 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:
2023-03-31 16:57:57 -04:00
| 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 | - | - |
2023-03-07 05:10:27 -05:00
| 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. |
2023-03-07 05:06:35 -05:00
Validations:
| Key | Description | Required | Type | Default | Valid values |
2023-03-31 16:57:57 -04:00
| -------- | ---------------------------------------------------- | -------- | ------- | ------- | ------------ |
2023-03-07 05:06:35 -05:00
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
2024-04-21 09:56:01 -04:00
visible: Default is ** [form, content]**
2023-03-07 05:06:35 -05:00
### 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 |
2023-03-31 16:57:57 -04:00
| ----------- | ------------------------------------------------------------------------------------------ | -------- | ------ | ------------ | ------------ |
2023-03-07 05:06:35 -05:00
| 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:
2024-04-21 09:56:01 -04:00
| 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]**
2023-03-07 05:06:35 -05:00
### Dropdown
You can use a `dropdown` element to add a dropdown menu in your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
2023-03-31 16:57:57 -04:00
| ----------- | --------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------ | ------------ |
2023-03-07 05:06:35 -05:00
| 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 |
2023-03-31 16:57:57 -04:00
| -------- | ---------------------------------------------------- | -------- | ------- | ------- | ------------ |
2023-03-07 05:06:35 -05:00
| required | Prevents form submission until element is completed. | Optional | Boolean | false | - |
2024-04-21 09:56:01 -04:00
visible: Default is ** [form, content]**
2023-03-07 05:06:35 -05:00
### Checkboxes
You can use the `checkboxes` element to add a set of checkboxes to your form.
Attributes:
| Key | Description | Required | Type | Default | Valid values |
2023-03-31 16:57:57 -04:00
| ----------- | ----------------------------------------------------------------------------------------------------- | -------- | ------ | ------------ | ------------ |
2023-03-07 05:06:35 -05:00
| 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.
2024-04-21 09:56:01 -04:00
| 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]**
2023-04-28 11:44:45 -04:00
## Syntax for issue config
2023-08-25 18:12:52 -04:00
This is an example for an issue config file
2023-04-28 11:44:45 -04:00
```yaml
blank_issues_enabled: true
contact_links:
2023-08-25 17:40:18 -04:00
- name: Forgejo
url: https://forgejo.org/
about: Visit the Forgejo Website
2023-04-28 11:44:45 -04:00
```
### Possible Options
| Key | Description | Type | Default |
| -------------------- | ----------------------------------------------------- | ------------------ | ----------- |
2023-08-25 18:12:52 -04:00
| 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 |
2023-04-28 11:44:45 -04:00
### Contact Link
| Key | Description | Type | Required |
| ----- | -------------------------------- | ------ | -------- |
| name | the name of your link | String | true |
2023-08-25 18:12:52 -04:00
| url | The URL of your link | String | true |
| about | A short description of your link | String | true |
