Issue Template

GitCode provides an Issue Template feature. By configuring issue templates with different contents, project maintainers can understand and resolve issues more quickly, while also enhancing the interactive experience for users when submitting suggestions or reporting problems. This article will detail how to create and configure Issue Templates.

What is an Issue Template?

An Issue Template is a predefined structured format used to standardize the information provided by users when creating an issue. Through templates, users can describe problems or requirements more clearly, while project maintainers can efficiently gather key information, thereby accelerating the resolution process.

Template Configuration Location

You can place Issue Templates in your project's .gitcode/ folder (create it if it doesn't exist), or in the docs/ or .gitcode/ISSUE_TEMPLATE/ directory, where you can create an ISSUE_TEMPLATE.md file. You can create multiple template files in the .gitcode/ISSUE_TEMPLATE/ folder. GitCode will display the created templates when users create an issue in this project for selection and use.

issue-tem-web

issue-tem-new

提示

Template configurations must be placed in the repository's default branch. If you create templates in other branches, the configuration will not take effect, and related features will be unavailable to collaborators.

The following is an example of a repository file tree using GitCode Issue Templates, showing the configuration location and file structure:

➜ git:(main) tree -L 2 .
.
├── .gitcode  # Compatible with the .github directory (prefer .gitcode)
│   ├── ISSUE_TEMPLATE    # Issue template configuration directory
│   │   ├── feature.yml   # Form template for feature suggestions
│   │   ├── bug.yml       # Form template for bug reports
│   │   ├── question.md   # Markdown template for inquiries
│   │   └── config.yml    # Template selector configuration file
│   └── issue_template.md # Blank issue template (optional)
├── LICENSE
├── README.md
└── src
    ├── index.js
    └── utils.js

5 directories, 8 files

How to Create an Issue Template

Currently, GitCode Issue Templates support the following two types of input formats:

Markdown: Traditional Issue templates composed of .md files. They generally provide guidance for the title and body of user issues, with relatively loose constraints.
Form YAML: You can create Issue templates with customizable web form fields. Using Issue Forms in your repository encourages contributors to provide specific structured information. Issue templates are written in YAML. For details, refer to YAML Form Syntax. If you are unfamiliar with YAML and wish to learn more, see Learn YAML in five minutes.

Markdown Template Configuration

In .md files, you can define basic template attributes by configuring front-matter information, such as the template name, title, default assignee, labels, etc. The body content will serve as the preset description when users create an issue.

Here is a simple Markdown template example:

---
name: Bug Report (.md template)
about: Report a problem to help us improve
title: "[BUG] "
labels: ["fix","bug"]
assignees: "f1325"
---

### BUG Type
<!-- Please describe the BUG type, e.g., UI, functionality, UX, etc. -->

### Reproduction Steps
<!-- Please describe the reproduction steps for the BUG in detail -->

提示

If you need to use a separator within the template, do not use three hyphens "---". This avoids conflicts with the divider symbol in the template rules. It is recommended to use four hyphens "----".

image-pr-tem

When a user creates an issue, this template automatically generates a title starting with [BUG], adds the bug label, and assigns it to the specified person. Additionally, the template provides two structured fields: BUG Type and Reproduction Steps, guiding users to describe the issue clearly.

Currently, GitCode supports the following front-matter configurations for Markdown:

Field	Description	Notes
`name`	Template Name	Use double quotes if it contains non-ASCII characters
`about`	Template Description	Use double quotes if it contains non-ASCII characters
`title`	Preset Issue Title	Use double quotes if it contains non-ASCII characters
`labels`	Issue Labels, supports multiple	Add multiple tags inside square brackets; if a tag does not exist, it will not be displayed when creating an issue
`assignees`	Default Issue Assignee	Username of the assignee

Form YAML Configuration Template

Templates in YAML format support more complex configurations, including preset assignees, labels, and custom form field types (such as text inputs, dropdown menus, radio buttons, checkboxes, code blocks, etc.).

Here is a YAML template example:

name: Bug Report (.yaml template)
description: Report a problem to help us improve
title: "[BUG] "
labels: ["bug"]
assignees: "yours_username"

body:
  - type: markdown
    attributes:
      value: |
        ## Thank you for your report!
        Please check if this issue has been reported before submission.

  - type: textarea
    id: details
    attributes:
      label: Issue Details
      description: Describe the issue symptoms, reproduction steps, and expected results.
      placeholder: Enter detailed information here
    validations:
      required: true

  - type: input
    id: what-happened
    attributes:
      label: Contact Information
      description: If further communication is needed, please leave your contact info (email/IM account).
      placeholder: "e.g., email@example.com"
    validations:
      required: false

  - type: checkboxes
    id: terms
    attributes:
      label: Confirmation
      description: Please confirm the following items.
      options:
        - label: I have searched existing issues and am confident this is a new one.
          required: true
        - label: I have read the relevant documentation.
          required: false
  
  - type: dropdown
    id: version
    attributes:
      label: Affected Version
      description: Please select the affected software version.
      options:
        - "1.0"
        - "2.0"
        - "3.0"
        - I'm not sure
      default: 0
    validations:
      required: true

  - type: cascading-dropdown
    id: project-module
    attributes:
      label: Project / Sub-module
      description: Select the project and corresponding module sequentially.
      options:
        - value: General AI Framework
          children: [Training Framework, Data Processing, Model Library]
        - value: Large Language Model Inference Engine
          children: [Inference Service, Quantization & Compression, VRAM Optimization]
        - value: Developer Toolchain
          children: [Debugging Tools, Performance Analysis, Visualization Dashboard]
    validations:
      required: false

The resulting form preview is as follows:

The specific field descriptions are as follows:

Field	Description	Notes
`name`	Template Name, Required	Used to define the template name
`description`	Template Description, Required	Used to explain the purpose of the template
`title`	Preset Issue Title, Optional	Use double quotes if it contains non-ASCII characters
`labels`	Issue Labels, Multiple Allowed, Optional	Multiple labels must use square brackets; if a label does not exist, it will not be displayed when creating an issue
`assignees`	Default Issue Assignee, Optional	Username of the assignee; ignored if the user does not exist
`body`	Form Configuration Content, Required	Supports various form types; for specific configurations, refer to YAML Form Syntax

Overview of YAML Form `type` Values

Each form element in the body declares its control type via the type attribute. The currently supported type values are enumerated below:

#	`type`	Description
1	`markdown`	Read-only Markdown text for display only; not submitted (does not enter the issue body)
2	`input`	Single-line text input
3	`textarea`	Multi-line Markdown text editor
4	`dropdown`	Dropdown menu
5	`checkboxes`	Checkbox group (individual options can set `required` to force selection)
6	`cascading-dropdown`	Cascading Dropdown (single-row component): Parent and child levels link within the same row; child options change based on the selected parent value

Configuring the Template Selector (config.yml)

By adding a config.yml file in the .gitcode/ISSUE_TEMPLATE directory, you can customize the template selector that users see when creating an issue.

Here is an example:

blank_issues_enabled: false  # Disable the option to create blank issues
contact_links:
  - name: GitCode Help Center
    url: https://docs.gitcode.com/
    about: We're here to help and answer any questions you may have while using GitCode

The fields in config.yml are explained as follows:

blank_issues_enabled: false: Disables the option for users to create blank issues without using a template. To allow blank issues, change the value to true.
contact_links: Provides links to external resources that users can access before creating an issue to get help or information.
- name: Link name, displayed on the issue creation page.
- url: Link URL.
- about: Short description of the link.

Preview effect:

Whether you use simple Markdown templates or complex YAML form templates, you can better manage issues in your project. We hope this article provides clear configuration guidance to help your project run efficiently.

What is an Issue Template?​

Template Configuration Location​

How to Create an Issue Template​

Markdown Template Configuration​

Form YAML Configuration Template​

Overview of YAML Form type Values​

Configuring the Template Selector (config.yml)​