---
url: /en/repo/issue-template.md
description: >
  Describes how to configure Issue templates in CNB repositories using YAML or
  Markdown format, placed in the .cnb/ISSUE_TEMPLATE directory, to standardize
  the issue creation process.
---
CNB supports Issue templates that help teams standardize the issue creation process, reduce missing
information, and improve efficiency.

## 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:

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

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

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

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

```yaml
validations:
  required: true # Make this field required
```

#### input (single-line input)

For short single-line text:

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

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

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

#### dropdown (select)

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

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

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

```markdown
---
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](https://cnb.cool/examples/templates/issue-templates).