Issue and Pull Request Templates

Issue and Pull Request templates help standardize the information contributors provide when creating issues or submitting pull requests. Templates guide users to include relevant details, making it easier for maintainers to understand and respond to contributions.

Overview

Templates in Forgejo are markdown files that provide a structured format for:

Issue templates - Guide users to provide complete bug reports, feature requests, or other issue types
Pull request templates - Help contributors describe their changes and provide context for reviewers

When users create a new issue or pull request, they can select from available templates or use a default template if one is configured.

Creating Issue Templates

Issue templates are stored in your repository’s .forgejo/issue_template/ directory.

Basic Issue Template

Create a file like .forgejo/issue_template/bug_report.md:

---
name: Bug Report
about: Report a bug or unexpected behavior
title: "[BUG] "
labels: ["bug"]
assignees: []
---

## Bug Description
A clear and concise description of what the bug is.

## Steps to Reproduce
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

## Expected Behavior
A clear and concise description of what you expected to happen.

## Actual Behavior
A clear and concise description of what actually happened.

## Environment
- OS: [e.g. Fedora 38]
- Browser: [e.g. Firefox 115]
- Version: [e.g. 1.0.0]

## Additional Context
Add any other context about the problem here, such as screenshots or logs.

Template Front Matter

The YAML front matter at the top of templates supports these fields:

Field Description

Field	Description
`name`	Display name for the template in the template selector
`about`	Brief description of when to use this template
`title`	Default title prefix for issues created with this template
`labels`	Array of labels to automatically apply to new issues
`assignees`	Array of usernames to automatically assign to new issues
`ref`	Default branch reference for the issue

name

Display name for the template in the template selector

about

Brief description of when to use this template

title

Default title prefix for issues created with this template

labels

Array of labels to automatically apply to new issues

assignees

Array of usernames to automatically assign to new issues

ref

Default branch reference for the issue

Multiple Issue Templates

You can create multiple templates for different issue types:

.forgejo/issue_template/bug_report.md - For bug reports
.forgejo/issue_template/feature_request.md - For feature requests
.forgejo/issue_template/question.md - For questions or support requests

Feature Request Template Example

---
name: Feature Request
about: Suggest a new feature or enhancement
title: "[FEATURE] "
labels: ["enhancement"]
assignees: []
---

## Feature Summary
A clear and concise description of the feature you'd like to see.

## Problem Statement
What problem does this feature solve? What use case does it address?

## Proposed Solution
Describe your preferred solution or approach.

## Alternatives Considered
Describe any alternative solutions or features you've considered.

## Additional Context
Add any other context, mockups, or examples about the feature request.

Creating Pull Request Templates

Pull request templates work differently from issue templates. While you can create multiple issue templates with a chooser interface, pull request templates are simpler - you can only have one template per repository, and it automatically appears as the default content when creating any new pull request.

Pull request templates are stored as a single file: .forgejo/pull_request_template.md.

Unlike issue templates, pull request templates do not support YAML front matter. Any YAML front matter will be displayed as plain text in the pull request body.

Pull Request Template

## Description
Brief description of the changes in this pull request.

## Type of Change
Please delete options that are not relevant:
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Related Issues
Fixes #(issue number)
Relates to #(issue number)

## Testing
Describe the tests you ran to verify your changes:
- [ ] Test A
- [ ] Test B

## Checklist
- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

## Screenshots (if applicable)
Add screenshots to help explain your changes.

Advanced Features

Issue Template Configuration

You can create a .forgejo/issue_template/config.yml file to control the issue creation experience and provide alternative support channels.

Configuration Options

The issue config file supports two main settings:

blank_issues_enabled (boolean, default: true): Controls whether users can create issues without using a template.
contact_links (array): Provides alternative ways to get help instead of creating an issue.

Controlling Blank Issues

When blank_issues_enabled: true (default): * Users can create "blank" issues without using any template * The issue template chooser shows a "Get Started" button for blank issues * Users have the option to skip all templates

When blank_issues_enabled: false: * Users cannot create blank issues * They must choose from available issue templates * Direct access to /issues/new redirects to /issues/new/choose * Forces structured issue creation

blank_issues_enabled: false

Adding Contact Links

Contact links appear on the issue template chooser page and provide alternative ways to get help:

contact_links:
  - name: Community Support
    url: https://discussion.fedoraproject.org
    about: Ask questions and get help from the community
  - name: Security Issues
    url: mailto:security@fedoraproject.org
    about: Report security vulnerabilities privately
  - name: Documentation
    url: https://docs.fedoraproject.org/en-US/forge-documentation/
    about: Check the documentation for common questions

Each contact link creates a card on the issue chooser page with:

Name - Bold title for the contact option
About - Description of when to use this option
External link button - Opens the URL in a new tab/window

Complete Configuration Example

# Disable blank issues to force template usage
blank_issues_enabled: false

# Provide alternative support channels
contact_links:
  - name: User Support Forum
    url: https://discussion.fedoraproject.org
    about: Get help from the community instead of filing a bug
  - name: Security Team
    url: mailto:security@fedoraproject.org
    about: Report security vulnerabilities privately
  - name: Feature Discussions
    url: https://discussion.fedoraproject.org/tag/fedora-forge
    about: Discuss new features before creating requests

Configuration File Location

Place the config file at:

.forgejo/issue_template/config.yml

Form-Based Templates

Forgejo also supports form-based issue templates using YAML syntax for more structured input. For complete documentation on form-based templates, see the official Forgejo YAML templates documentation.

Additional Resources

Want to help? Learn how to contribute to Fedora Docs ›