GitHub Templates and Community Files

Guide contributors with issue and pull request templates, start new projects quickly from template repositories, and add the community files every healthy project has.

Lesson 11 of 30Intermediate17 min read

As soon as other people start using your project, the same problems appear again and again. Bug reports arrive with no steps to reproduce. Pull requests come with an empty description, so reviewers have to ask what changed and why. Newcomers don't know how to run the tests or what style the code follows. Every new project you start needs the same setup files copied from the last one.

GitHub has a simple fix for each of these: templates and community files. Templates pre-fill new issues and pull requests with the questions you always need answered. A template repository lets you start new projects from a ready-made structure in one click. And a handful of standard files, like CONTRIBUTING.md and a code of conduct, tell people how to take part.

All of them are ordinary files committed to the repository, mostly in a .github folder. In this lesson you'll create each one and see how it appears to the people using your project.

Issue templates

Put Markdown files in .github/ISSUE_TEMPLATE/. Each one becomes a choice when someone clicks New issue:

Markdown
---
name: Bug report
about: Something isn't working
labels: bug
---
**What happened?**

**Steps to reproduce**
1.

**What did you expect?**

The section at the top between the --- lines sets the name, description and labels. For required fields and drop-down menus, use YAML issue forms, which you met in the Projects lesson. A config.yml in the same folder can turn off blank issues and add links, for example to your Discussions page for questions.

Pull request templates

Create .github/pull_request_template.md, and its contents fill the description box of every new pull request:

Markdown
## What does this change?

## How was it tested?

## Checklist
- [ ] Tests added or updated
- [ ] Docs updated
- [ ] Screenshots for visual changes

Keep it short: three or four questions people will actually answer. The task list checkboxes show progress on the pull request page. For several kinds of PR, add files in a PULL_REQUEST_TEMPLATE folder and choose one with a ?template= link.

Template repositories

In a repository's Settings, tick Template repository. A Use this template button appears, which creates a new repository with all the same files and folders, but a fresh history and no link back to the original.

This is perfect for a team's standard starter: folder structure, .gitignore, licence, issue templates, a GitHub Actions workflow and a README outline, all ready from the first minute. Unlike a fork, a repository created from a template is completely independent and can be private even if the template is public.

Community health files

FileTells people
README.mdWhat the project is and how to use it
LICENSEWhat others may legally do with the code
CONTRIBUTING.mdHow to set up, test, and submit changes
CODE_OF_CONDUCT.mdExpected behaviour and how problems are handled
SECURITY.mdHow to report vulnerabilities privately
SUPPORT.mdWhere to get help

GitHub links these automatically from the right places, such as the new issue page and the repository sidebar. Insights, then Community standards, shows a checklist of which ones your project has. An organisation can create a repository called .github holding default versions used by every repository that doesn't have its own.

GitHub Templates Syntax

Template locations

.github/ISSUE_TEMPLATE/bug_report.md
.github/ISSUE_TEMPLATE/feature_request.yml
.github/ISSUE_TEMPLATE/config.yml
.github/pull_request_template.md
.github/PULL_REQUEST_TEMPLATE/release.md
CONTRIBUTING.md  CODE_OF_CONDUCT.md  SECURITY.md  SUPPORT.md  LICENSE
Settings > General > Template repository

GitHub Templates Summary

  • Issue templates live in .github/ISSUE_TEMPLATE; config.yml can disable blank issues and add links.
  • A pull_request_template.md pre-fills every new pull request's description.
  • Mark a repository as a Template repository to start new projects from it with Use this template.
  • Community files such as CONTRIBUTING.md, CODE_OF_CONDUCT.md and SECURITY.md guide contributors.
  • A .github repository in an organisation provides default files for all its repositories.

GitHub Templates Examples

Each example shows the code, the output it produces and what each part does.

Example 1

A bug report template and chooser settings

YAML
# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: Questions and help
    url: https://github.com/samlee/recipe-box/discussions
    about: Ask questions in Discussions instead of opening an issue.
Output
New issue page:
  Bug report            Something isn't working          [Get started]
  Feature request       Suggest an idea                  [Get started]
  Questions and help    Ask questions in Discussions...  [Open]
(no "Open a blank issue" link)
Line-by-line explanation
  1. Line 2Everyone must pick a template, so every report has the right sections.
  2. Lines 3 to 6Extra links appear in the chooser, sending questions to Discussions.
Example 2

A pull request template in use

Markdown
<!-- .github/pull_request_template.md -->
## What does this change?
<!-- One or two sentences. Link the issue: Closes #12 -->

## How was it tested?

## Checklist
- [ ] Tests pass locally
- [ ] Screenshots added for visual changes
Output
Opening a pull request shows the description already filled with
these headings. The HTML comments are hidden once it's posted,
and the checklist shows "0 of 2 tasks" in the pull request list.
Line-by-line explanation
  1. Line 1Saved in the .github folder, it applies to every new pull request.
  2. Line 3HTML comments give hints that disappear from the final description.
  3. Lines 7 to 9Task list items become a progress count on the PR.
Example 3

A CONTRIBUTING.md

Markdown
# Contributing to Recipe Box

Thanks for helping! Here's how to get started.

## Set up
1. Fork the repository and clone your fork.
2. Run `npm install`, then `npm run dev` to start the site.

## Making a change
- Create a branch: `fix/short-description` or `feature/short-description`.
- Run `npm test` before opening a pull request.
- Keep pull requests small and focused on one change.

## Good first issues
Look for issues labelled `good first issue`. Comment on one to say
you're working on it, so nobody else starts the same thing.
Output
GitHub shows a "Contributing" link in the repository sidebar
and on the new issue and new pull request pages.
Line-by-line explanation
  1. Lines 5 to 7Setup steps a newcomer can follow exactly, as described in the forks lesson.
  2. Lines 9 to 12The team's branch naming and testing rules in one place.
  3. Lines 14 to 16Points beginners to suitable issues and avoids duplicated work.

Common GitHub Templates Mistakes

Templates in the wrong place

Don't
ISSUE_TEMPLATE.md in a docs/ folder that GitHub doesn't check
Do
.github/ISSUE_TEMPLATE/bug_report.md
.github/pull_request_template.md

A template nobody will fill in

Don't
## Environment
## OS version
## Browser version
## Node version
## Steps
## Logs
## Screenshots
## Related issues
## Additional context
Do
## Steps to reproduce
## What you expected
## What happened (with browser and version)

Forking to start a new project

Don't
Fork the starter repository for every new project   -> linked forks, public only
Do
Mark the starter as a Template repository and use "Use this template"

GitHub Templates in Real Projects

Templates in open source and teams

Popular open-source projects such as VS Code, React and Rust use issue forms to collect versions and reproduction steps, which saves maintainers hours every week. Companies keep template repositories for each kind of service, so every new project starts with the same CI, linting and security settings. GitHub's Community standards checklist is a quick health check before you announce a project publicly.

GitHub Templates FAQ

How do I add labels automatically with an issue template?

In a Markdown issue template, add a labels: line to the front matter at the top, such as labels: bug. In a YAML issue form, add a labels: list. Every issue created from that template gets those labels, which makes triage much faster.

Why doesn't my issue template show up?

The template must be on the repository's default branch, inside .github/ISSUE_TEMPLATE/, with a valid name and about (or description for issue forms) at the top. A YAML mistake can also stop it appearing, so check the file carefully after editing.

Can I share templates across every repository in an organization?

Yes. Create a public repository called .github in the organization and put templates and community health files there. Repositories that don't have their own versions use those defaults. A repository's own files always win.

What gets copied when I use a template repository?

The files and folders from the template's default branch, or from all branches if you tick the option to include them. The history isn't copied: your new repository starts with a single fresh commit. Issues, pull requests and settings aren't copied either.

Can I pre-fill a new issue from a link?

Yes. Add query parameters to the new-issue URL, such as /issues/new?title=Bug&labels=bug&body=Steps..., with the values URL-encoded. You can also add template=bug_report.md to choose a template. It's handy for "Report a problem" links in your app or documentation.

GitHub Templates Exercises

Answer each one and check it instantly. If you get stuck, open the hint before the answer.

Fill in the blankseasy

Complete the path for a pull request template.

.github/
Multiple choiceeasy

Where do issue templates go?

Multiple choicemedium

What does blank_issues_enabled: false do?

Multiple choicemedium

What's the difference between a fork and a repository created from a template?

Multiple choicehard

How can an organisation give all its repositories a default CODE_OF_CONDUCT.md?

GitHub Templates Quiz

5 questions to check what you learned.

  1. Which file explains how to contribute to a project?

    • CONTRIBUTING.md
    • LICENSE
    • .gitignore
    • package.json

  2. Where do you mark a repository as a template?

    • In the README
    • In .github/config.yml
    • With a topic
    • In the repository's Settings, General section

  3. What does the Community standards page show?

    • Commit statistics
    • Code style errors
    • A checklist of recommended community files and whether the project has them
    • Open pull requests

  4. Why are HTML comments useful in templates?

    • They're required
    • They show hints while writing but are hidden in the posted text
    • They make text bold
    • They add labels

  5. Why keep templates short?

    • GitHub limits them to 5 lines
    • Short templates load faster
    • Markdown can't handle long files
    • Long templates tend to be ignored or deleted, so ask only what you'll actually use

Related GitHub topics

07IssuesReport bugs and plan work with issues, labels, assignees and milestones, and link issues to commits and pull requests.08Pull RequestsPropose changes from a branch, review them, respond to feedback and merge with a pull request.12Projects & DiscussionsPlan and track work with GitHub Projects boards, tables and roadmaps, automate status changes, and use Discussions and issue forms.
Esc
↑↓ to navigateEnter to open