Issue Template

About 968 wordsAbout 3 min

Issue Templates explains how to configure issue templates for a repository.

When to use: when issue reports should be more complete — for example making a bug reporter fill in reproduction steps and version, or a feature requester fill in background and acceptance criteria, reducing back-and-forth questions.

CNB supports both YAML and Markdown templates; place them in the repository's .cnb/ISSUE_TEMPLATE directory to take effect.

Storage Directory

All Issue template files must be placed in the .cnb/ISSUE_TEMPLATE directory on your repository's default branch, and both the directory and files must be committed to the repository:

.cnb/
└── ISSUE_TEMPLATE/
    ├── config.yml          # (optional) Template chooser configuration
    ├── bug-report.yml      # YAML template
    └── feature-request.md  # Markdown template

Tips

Templates are read from the repository's default branch (e.g., main / master). Templates not on that branch will not be recognized.

Supported File Formats

The following template file formats are supported in the directory:

Extension	Description
`.yml` / `.yaml`	YAML form template that defines various input components. Recommended
`.md`	Markdown template whose full content is used as the issue body

File Limits

To prevent large files from affecting performance, templates have the following limits:

The maximum size of a single template file is 256 KB; larger files are ignored
At most 10 template files are recognized in the directory

Template Chooser Configuration (Optional)

Place config.yml (or config.yaml) in the .cnb/ISSUE_TEMPLATE directory to configure the template chooser page when creating an issue, including whether blank issues are allowed and the contact links to show:

blank_issues_enabled: false # Whether to allow creating a blank issue. Default: true
contact_links:
  - name: Usage Help
    url: https://cnb.cool/docs
    about: Get help here for questions you encounter

YAML Template

A YAML template composes an issue form from multiple "components". Users fill in each item when creating an issue, and the filled content is appended to the issue body in template order.

Top-Level Fields

The YAML template supports the following top-level fields:

Field	Type	Required	Description
`name`	string	Yes	Template name, shown on the chooser page
`description`	string	Yes	Template description, shown on the chooser page
`title`	string	No	Pre-filled issue title, editable by the user
`labels`	string[]	No	Labels automatically added on creation
`assignees`	string[]	No	Assignees automatically assigned on creation
`body`	object[]	No	List of form components, see below

name: Bug Report
description: A template for submitting bugs
title: "[Bug] "
labels: ["bug"]
assignees: ["userA"]
body:
  # ... component definitions

Form Components

Each item under body is a component, identified by type, with properties in attributes and validation rules in validations.

The following attributes are common to all components:

Attribute	Type	Description
`label`	string	Field title shown above the input; also the field name in the issue body
`description`	string	Field description shown below the title; supports Markdown
`placeholder`	string	Placeholder text for the input

Validation rules are declared via validations. Currently a required check is supported:

validations:
  required: true # Make this field required

input (single-line input)

For short single-line text:

- type: input
  attributes:
    label: Version
    description: The product version you are using
    placeholder: e.g. 1.0.0
  validations:
    required: true

textarea (multi-line input)

For longer text. By default it renders as a Markdown editor with rich text and image upload. Use render: text to render a plain textarea instead:

# Default: Markdown editor
- type: textarea
  attributes:
    label: Reproduction Steps
    placeholder: Please describe the full reproduction steps
  validations:
    required: true

# render: text renders a plain textarea
- type: textarea
  attributes:
    label: Error Log
    render: text
    placeholder: Paste the full error log here

markdown (read-only text)

Inserts read-only Markdown explanatory text into the form; users cannot edit it. By default this content is not written to the issue body and is only displayed. Set includeInBody: true to also append it to the body:

- type: markdown
  attributes:
    value: |
      Thanks for submitting an issue. Please read the [Contributing Guide](https://cnb.cool) before filling it out.
  # includeInBody is disabled, so this text is displayed only

- type: markdown
  attributes:
    value: |
      ## Environment
    includeInBody: true # This text is also appended to the issue body

Provides a dropdown selection; single-select by default. Set multiple: true to enable multi-select:

- type: dropdown
  attributes:
    label: Impact Scope
    options:
      - Frontend
      - Backend
      - Data
  validations:
    required: true

# Multi-select dropdown
- type: dropdown
  attributes:
    label: Affected Modules
    multiple: true
    options:
      - Authentication
      - Billing
      - Pipeline

checkboxes (checkbox list)

Provides a set of checkable options, often used as a self-check list. Each option can be marked as required via required: true:

- type: checkboxes
  attributes:
    label: Pre-Submit Checklist
    options:
      - label: Reproduced the issue
        required: true
      - label: Added logs
      - label: Confirmed no sensitive information

Markdown Template

A Markdown template uses the full content of the .md file as the issue body shown to the user, who can edit it directly on the creation page. YAML Front Matter at the top of the file configures the template metadata:

---
name: Feature Request
about: A template for feature requests
title: "[Feature] "
labels: feature
assignees: userA
---

## Background

Please describe the feature you want……

## Expected Behavior

Please describe the expected interaction……

Front Matter Field	Type	Required	Description
`name`	string	Yes	Template name
`about`	string	Yes	Template description
`title`	string	No	Pre-filled issue title
`labels`	string	No	Pre-filled labels, comma-separated
`assignees`	string	No	Pre-filled assignees, comma-separated

Creating an Issue

On the "New Issue" page of a repository, CNB automatically reads the templates under .cnb/ISSUE_TEMPLATE and shows the template chooser. After selecting a template, users fill out the corresponding form and submit to create an issue.

For more examples, see the sample repository: issue-templates.