code.gitea.io/gitea@v1.22.3/docs/content/usage/issue-pull-request-templates.en-us.md (about) 1 --- 2 date: "2018-05-10T16:00:00+02:00" 3 title: "Issue and Pull Request templates" 4 slug: "issue-pull-request-templates" 5 sidebar_position: 15 6 toc: false 7 draft: false 8 aliases: 9 - /en-us/issue-pull-request-templates 10 menu: 11 sidebar: 12 parent: "usage" 13 name: "Issue and Pull Request templates" 14 sidebar_position: 15 15 identifier: "issue-pull-request-templates" 16 --- 17 18 # Issue and Pull Request Templates 19 20 Some projects have a standard list of questions that users need to answer 21 when creating an issue or pull request. Gitea supports adding templates to the 22 **default branch of the repository** so that they can autopopulate the form when users are 23 creating issues and pull requests. This will cut down on the initial back and forth 24 of getting some clarifying details. 25 It is currently not possible to provide generic issue/pull-request templates globally. 26 27 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. 28 29 ## File names 30 31 Possible file names for issue templates: 32 33 - `ISSUE_TEMPLATE.md` 34 - `ISSUE_TEMPLATE.yaml` 35 - `ISSUE_TEMPLATE.yml` 36 - `issue_template.md` 37 - `issue_template.yaml` 38 - `issue_template.yml` 39 - `.gitea/ISSUE_TEMPLATE.md` 40 - `.gitea/ISSUE_TEMPLATE.yaml` 41 - `.gitea/ISSUE_TEMPLATE.yml` 42 - `.gitea/issue_template.md` 43 - `.gitea/issue_template.yaml` 44 - `.gitea/issue_template.yml` 45 - `.github/ISSUE_TEMPLATE.md` 46 - `.github/ISSUE_TEMPLATE.yaml` 47 - `.github/ISSUE_TEMPLATE.yml` 48 - `.github/issue_template.md` 49 - `.github/issue_template.yaml` 50 - `.github/issue_template.yml` 51 52 Possible file names for issue config: 53 54 - `.gitea/ISSUE_TEMPLATE/config.yaml` 55 - `.gitea/ISSUE_TEMPLATE/config.yml` 56 - `.gitea/issue_template/config.yaml` 57 - `.gitea/issue_template/config.yml` 58 - `.github/ISSUE_TEMPLATE/config.yaml` 59 - `.github/ISSUE_TEMPLATE/config.yml` 60 - `.github/issue_template/config.yaml` 61 - `.github/issue_template/config.yml` 62 63 Possible file names for PR templates: 64 65 - `PULL_REQUEST_TEMPLATE.md` 66 - `PULL_REQUEST_TEMPLATE.yaml` 67 - `PULL_REQUEST_TEMPLATE.yml` 68 - `pull_request_template.md` 69 - `pull_request_template.yaml` 70 - `pull_request_template.yml` 71 - `.gitea/PULL_REQUEST_TEMPLATE.md` 72 - `.gitea/PULL_REQUEST_TEMPLATE.yaml` 73 - `.gitea/PULL_REQUEST_TEMPLATE.yml` 74 - `.gitea/pull_request_template.md` 75 - `.gitea/pull_request_template.yaml` 76 - `.gitea/pull_request_template.yml` 77 - `.github/PULL_REQUEST_TEMPLATE.md` 78 - `.github/PULL_REQUEST_TEMPLATE.yaml` 79 - `.github/PULL_REQUEST_TEMPLATE.yml` 80 - `.github/pull_request_template.md` 81 - `.github/pull_request_template.yaml` 82 - `.github/pull_request_template.yml` 83 84 ## Directory names 85 86 Alternatively, users can create multiple issue templates inside a special directory and allow users to choose one that more specifically 87 addresses their problem. 88 89 Possible directory names for issue templates: 90 91 - `ISSUE_TEMPLATE` 92 - `issue_template` 93 - `.gitea/ISSUE_TEMPLATE` 94 - `.gitea/issue_template` 95 - `.github/ISSUE_TEMPLATE` 96 - `.github/issue_template` 97 - `.gitlab/ISSUE_TEMPLATE` 98 - `.gitlab/issue_template` 99 100 Inside the directory can be multiple markdown (`.md`) or yaml (`.yaml`/`.yml`) issue templates of the form. 101 102 ## Syntax for markdown template 103 104 ```md 105 --- 106 107 name: "Template Name" 108 about: "This template is for testing!" 109 title: "[TEST] " 110 ref: "main" 111 labels: 112 113 - bug 114 - "help needed" 115 116 --- 117 118 This is the template! 119 ``` 120 121 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 122 `This template is for testing!`. When submitting an issue with the above example, the issue title would be pre-populated with 123 `[TEST] ` while the issue body would be pre-populated with `This is the template!`. The issue would also be assigned two labels, 124 `bug` and `help needed`, and the issue will have a reference to `main`. 125 126 ## Syntax for yaml template 127 128 This example YAML configuration file defines an issue form using several inputs to report a bug. 129 130 ```yaml 131 name: Bug Report 132 about: File a bug report 133 title: "[Bug]: " 134 body: 135 - type: markdown 136 attributes: 137 value: | 138 Thanks for taking the time to fill out this bug report! 139 # some markdown that will only be visible once the issue has been created 140 - type: markdown 141 attributes: 142 value: | 143 This issue was created by an issue **template** :) 144 visible: [content] 145 - type: input 146 id: contact 147 attributes: 148 label: Contact Details 149 description: How can we get in touch with you if we need more info? 150 placeholder: ex. email@example.com 151 validations: 152 required: false 153 - type: textarea 154 id: what-happened 155 attributes: 156 label: What happened? 157 description: Also tell us, what did you expect to happen? 158 placeholder: Tell us what you see! 159 value: "A bug happened!" 160 validations: 161 required: true 162 - type: dropdown 163 id: version 164 attributes: 165 label: Version 166 description: What version of our software are you running? 167 options: 168 - 1.0.2 (Default) 169 - 1.0.3 (Edge) 170 validations: 171 required: true 172 - type: dropdown 173 id: browsers 174 attributes: 175 label: What browsers are you seeing the problem on? 176 multiple: true 177 options: 178 - Firefox 179 - Chrome 180 - Safari 181 - Microsoft Edge 182 - type: textarea 183 id: logs 184 attributes: 185 label: Relevant log output 186 description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. 187 render: shell 188 - type: checkboxes 189 id: terms 190 attributes: 191 label: Code of Conduct 192 description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com) 193 options: 194 - label: I agree to follow this project's Code of Conduct 195 required: true 196 - label: I have also read the CONTRIBUTION.MD 197 required: true 198 visible: [form] 199 - label: This is a TODO only visible after issue creation 200 visible: [content] 201 ``` 202 203 ### Markdown 204 205 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. 206 207 Attributes: 208 209 | Key | Description | Required | Type | Default | Valid values | 210 |-------|--------------------------------------------------------------|----------|--------|---------|--------------| 211 | value | The text that is rendered. Markdown formatting is supported. | Required | String | - | - | 212 213 visible: Default is **[form]** 214 215 ### Textarea 216 217 You can use a `textarea` element to add a multi-line text field to your form. Contributors can also attach files in `textarea` fields. 218 219 Attributes: 220 221 | Key | Description | Required | Type | Default | Valid values | 222 |-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------|--------------|---------------------------| 223 | label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - | 224 | description | A description of the text area to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - | 225 | placeholder | A semi-opaque placeholder that renders in the text area when empty. | Optional | String | Empty String | - | 226 | value | Text that is pre-filled in the text area. | Optional | String | - | - | 227 | 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 Gitea. | 228 229 Validations: 230 231 | Key | Description | Required | Type | Default | Valid values | 232 |----------|------------------------------------------------------|----------|---------|---------|--------------| 233 | required | Prevents form submission until element is completed. | Optional | Boolean | false | - | 234 235 visible: Default is **[form, content]** 236 237 ### Input 238 239 You can use an `input` element to add a single-line text field to your form. 240 241 Attributes: 242 243 | Key | Description | Required | Type | Default | Valid values | 244 |-------------|--------------------------------------------------------------------------------------------|----------|--------|--------------|--------------| 245 | label | A brief description of the expected user input, which is also displayed in the form. | Required | String | - | - | 246 | description | A description of the field to provide context or guidance, which is displayed in the form. | Optional | String | Empty String | - | 247 | placeholder | A semi-transparent placeholder that renders in the field when empty. | Optional | String | Empty String | - | 248 | value | Text that is pre-filled in the field. | Optional | String | - | - | 249 250 Validations: 251 252 | Key | Description | Required | Type | Default | Valid values | 253 |-----------|--------------------------------------------------------------------------------------------------|----------|---------|---------|--------------------------------------------------------------------------| 254 | required | Prevents form submission until element is completed. | Optional | Boolean | false | - | 255 | is_number | Prevents form submission until element is filled with a number. | Optional | Boolean | false | - | 256 | 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) | 257 258 visible: Default is **[form, content]** 259 260 ### Dropdown 261 262 You can use a `dropdown` element to add a dropdown menu in your form. 263 264 Attributes: 265 266 | Key | Description | Required | Type | Default | Valid values | 267 |-------------|-----------------------------------------------------------------------------------------------------|----------|--------------|--------------|--------------| 268 | label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - | 269 | description | A description of the dropdown to provide extra context or guidance, which is displayed in the form. | Optional | String | Empty String | - | 270 | multiple | Determines if the user can select more than one option. | Optional | Boolean | false | - | 271 | options | An array of options the user can choose from. Cannot be empty and all choices must be distinct. | Required | String array | - | - | 272 273 Validations: 274 275 | Key | Description | Required | Type | Default | Valid values | 276 |----------|------------------------------------------------------|----------|---------|---------|--------------| 277 | required | Prevents form submission until element is completed. | Optional | Boolean | false | - | 278 279 visible: Default is **[form, content]** 280 281 ### Checkboxes 282 283 You can use the `checkboxes` element to add a set of checkboxes to your form. 284 285 Attributes: 286 287 | Key | Description | Required | Type | Default | Valid values | 288 | ----------- | ----------------------------------------------------------------------------------------------------- | -------- | ------ | ------------ | ------------ | 289 | label | A brief description of the expected user input, which is displayed in the form. | Required | String | - | - | 290 | description | A description of the set of checkboxes, which is displayed in the form. Supports Markdown formatting. | Optional | String | Empty String | - | 291 | options | An array of checkboxes that the user can select. For syntax, see below. | Required | Array | - | - | 292 293 For each value in the options array, you can set the following keys. 294 295 | Key | Description | Required | Type | Default | Options | 296 |--------------|------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------|---------|---------| 297 | 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 | - | - | 298 | required | Prevents form submission until element is completed. | Optional | Boolean | false | - | 299 | 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 | - | 300 301 visible: Default is **[form, content]** 302 303 ## Syntax for issue config 304 305 This is a example for a issue config file 306 307 ```yaml 308 blank_issues_enabled: true 309 contact_links: 310 - name: Gitea 311 url: https://gitea.com 312 about: Visit the Gitea Website 313 ``` 314 315 ### Possible Options 316 317 | Key | Description | Type | Default | 318 |----------------------|-------------------------------------------------------|--------------------|-------------| 319 | blank_issues_enabled | If set to false, the User is forced to use a Template | Boolean | true | 320 | contact_links | Custom Links to show in the Choose Box | Contact Link Array | Empty Array | 321 322 ### Contact Link 323 324 | Key | Description | Type | Required | 325 |-------|----------------------------------|--------|----------| 326 | name | the name of your link | String | true | 327 | url | The URL of your Link | String | true | 328 | about | A short description of your Link | String | true |