GitHub 16 🌐 .github Directory and Repository Templates - KandZ

⏱️ Estimated read: 9 min | |

A repository is more than a folder of code. It is a workspace with rules, workflows, and community expectations. GitHub defines a special directory, .github, where configuration files that shape the repository’s behavior live. The files inside this directory are not code—they are the contracts that govern how contributions are made, how issues are triaged, and how the repository presents itself to the outside world. Mastering .github is the difference between a repository that feels maintained and one that feels abandoned.

Key point: The .github directory is a convention, not a requirement. GitHub looks there first for issue templates, pull request templates, CODEOWNERS, workflows, and community health files. If a file is not in .github, GitHub looks in the repository root. The .github directory keeps configuration separate from source code.

Why the `.github` directory exists

The clutter problem. A repository root is for source code. Placing configuration files alongside src/, tests/, and README.md makes the root directory a mix of code and meta-configuration. The .github directory was introduced to create a dedicated space for files that GitHub reads but users rarely edit. The visual result is a cleaner root and a clear separation of concerns .

The discovery problem. Issue templates and pull request templates are only useful if contributors see them. GitHub looks for templates in .github/ISSUE_TEMPLATE/ and .github/PULL_REQUEST_TEMPLATE.md automatically. If a template is placed elsewhere, it is ignored. The .github directory is the only place where GitHub’s automatic discovery works reliably .

The organization-wide defaults problem. An organization can create a .github repository (named exactly .github) at the organization level. This repository can contain community health files, issue templates, and workflows that apply to every repository in the organization. Individual repositories can override these defaults by providing their own files in their .github directory .

The community health problem. GitHub evaluates a repository’s community profile based on the presence of files like CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, and LICENSE. These files can live in the root, in .github, or in docs. GitHub scans all three locations and displays the community profile based on the first one it finds. Placing them in .github keeps the root clean while still satisfying the profile check .

The trade-off. The .github directory hides configuration from casual browsing. A developer who clones the repository sees .github/ and may not know what is inside. The convention is that anything in .github is GitHub-specific and not part of the build or runtime. The trade-off is accepted for cleaner roots and reliable discovery.

a. Issue and pull request templates

Issue templates live in .github/ISSUE_TEMPLATE/. They can be Markdown files with YAML frontmatter or YAML Issue Forms. The config.yml file inside the same directory configures the template chooser, including whether blank issues are allowed and whether external links should be displayed.

.github/
└── ISSUE_TEMPLATE/
    ├── bug_report.yml
    ├── feature_request.md
    └── config.yml

A pull request template lives at .github/PULL_REQUEST_TEMPLATE.md (or as a directory with multiple templates). When a contributor opens a pull request, the template is pre-filled in the description field.

<!-- .github/PULL_REQUEST_TEMPLATE.md -->
## Description
Brief description of the change.

## Related Issue
Fixes #(issue)

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change

## Checklist
- [ ] Tests pass locally
- [ ] Documentation updated
- [ ] Follows the project's style guidelines

The pull request template is not enforced. A contributor can delete it. But it serves as a prompt and a reminder. In practice, the presence of a template increases the quality of pull requests because contributors follow the structure it provides.

b. Community health files and CODEOWNERS

The .github directory can hold community health files: CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, and FUNDING.yml. GitHub scans the root, .github/, and docs/ for these files, in that order. Placing them in .github keeps the root free for source code while still satisfying the community profile .

The CODEOWNERS file is read from .github/CODEOWNERS, CODEOWNERS (root), or docs/CODEOWNERS. The .github location is the convention for new repositories. The file maps file patterns to users or teams, and when combined with “Require review from Code Owners” in branch protection, it enforces domain-specific review .

# .github/CODEOWNERS
*           @core-team
/docs/      @technical-writers
/security/  @security-team

The FUNDING.yml file, located at .github/FUNDING.yml, configures the “Sponsor” button that appears at the top of the repository. It lists GitHub Sponsors, Patreon, Ko-fi, and other funding platforms.

c. Workflows and organization-wide defaults

The .github/workflows/ directory holds GitHub Actions workflow files. Each YAML file defines a workflow triggered by events like push, pull_request, or schedule. GitHub reads every .yml or .yaml file in this directory; files elsewhere in the repository are ignored .

.github/
└── workflows/
    ├── ci.yml
    ├── release.yml
    └── codeql.yml

An organization can create a repository named .github at the organization level. The .github directory inside that repository can contain workflows/ that are shared across all organization repositories. Workflows in the organization’s .github repository are visible to all repositories but are only executed if invoked explicitly or if they match the trigger conditions .

Community health files in the organization’s .github repository serve as defaults. If an individual repository does not have a CONTRIBUTING.md, GitHub uses the one from the organization’s .github repository. This allows central management of community guidelines while letting individual repositories override when necessary .

Complete Example Session

# ============================================
# PART 1: CREATE THE DIRECTORY STRUCTURE
# ============================================

mkdir -p .github/ISSUE_TEMPLATE .github/workflows

# ============================================
# PART 2: ADD AN ISSUE TEMPLATE
# ============================================

cat > .github/ISSUE_TEMPLATE/bug_report.yml <<'EOF'
name: Bug Report
description: File a bug report.
labels: ["bug"]
body:
  - type: textarea
    attributes:
      label: What happened?
    validations:
      required: true
EOF

# ============================================
# PART 3: ADD A PULL REQUEST TEMPLATE
# ============================================

cat > .github/PULL_REQUEST_TEMPLATE.md <<'EOF'
## Description

## Related Issue
Fixes #

## Checklist
- [ ] Tests pass
- [ ] Documentation updated
EOF

# ============================================
# PART 4: ADD CODEOWNERS
# ============================================

cat > .github/CODEOWNERS <<'EOF'
*       @core-team
/docs/  @tech-writers
EOF

# ============================================
# PART 5: ADD A WORKFLOW
# ============================================

cat > .github/workflows/ci.yml <<'EOF'
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test
EOF

# ============================================
# PART 6: ADD COMMUNITY HEALTH FILES
# ============================================

echo "# Contributing" > .github/CONTRIBUTING.md
echo "# Security Policy" > .github/SECURITY.md

# ============================================
# PART 7: COMMIT AND PUSH
# ============================================

git add .github
git commit -m "Add GitHub configuration"
git push origin main

# ============================================
# PART 8: VERIFY TEMPLATE CHOOSER
# ============================================

# Navigate to repository → Issues → New issue
# The template chooser displays the bug_report.yml option.

# ============================================
# PART 9: VERIFY COMMUNITY PROFILE
# ============================================

# Navigate to repository → Insights → Community Standards
# GitHub detects the health files in .github.

The nine parts trace the .github lifecycle: directory creation, issue template, pull request template, CODEOWNERS, workflow, community health files, commit, verification of the template chooser, and verification of the community profile.

Quick Reference

`.github` Directory Structure

Path	Purpose
`.github/workflows/`	GitHub Actions workflows
`.github/ISSUE_TEMPLATE/`	Issue templates and config
`.github/PULL_REQUEST_TEMPLATE.md`	Pull request template
`.github/CODEOWNERS`	Review assignment rules
`.github/CONTRIBUTING.md`	Contribution guidelines
`.github/SECURITY.md`	Security policy
`.github/FUNDING.yml`	Sponsor button configuration

File Discovery Order

File Type	Search Order
Issue templates	`.github/ISSUE_TEMPLATE/` only
Pull request template	`.github/`, root, `docs/`
CODEOWNERS	`.github/`, root, `docs/`
Community health	`.github/`, root, `docs/`
Workflows	`.github/workflows/` only

Organization-Wide Defaults

Repository	Purpose
`.github` (org-level)	Shared templates, health files, workflows
Individual repo	Overrides org defaults when present

Best Practices

✅ Do This:

.github/ISSUE_TEMPLATE/bug_report.yml
<!-- Use Issue Forms for structured reports -->       # ✅

.github/CODEOWNERS
<!-- Place CODEOWNERS in .github/ -->                # ✅

.github/workflows/ci.yml
<!-- Workflows must be in .github/workflows/ -->      # ✅

❌ Don’t Do This:

# Put issue templates in the repository root
<!-- GitHub only checks .github/ISSUE_TEMPLATE/ -->   # ❌

# Put workflows in a subdirectory
<!-- GitHub only reads .github/workflows/ top level --> # ❌

# Duplicate community health files in every repo
<!-- Use the organization-level .github repo -->       # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Issue template not showing	Placed outside `.github/ISSUE_TEMPLATE/`	Move to the correct directory
Workflow not running	Placed outside `.github/workflows/`	Move to the correct directory
CODEOWNERS not applied	Not on default branch	Commit to `main`
Community profile incomplete	Health files in non-standard location	Move to `.github/` or root
Organization defaults not used	Individual repo has conflicting file	Remove the local file to inherit

Real-World Examples

1. Issue Form

# .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug Report
labels: ["bug"]
body:
  - type: textarea
    attributes:
      label: What happened?

2. Pull Request Template

<!-- .github/PULL_REQUEST_TEMPLATE.md -->
## Description
## Related Issue
Fixes #

3. CODEOWNERS

# .github/CODEOWNERS
*       @core-team
/docs/  @tech-writers

4. Workflow

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

5. Config Chooser

# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false

6. Security Policy

# .github/SECURITY.md

7. Contributing Guide

# .github/CONTRIBUTING.md

8. Funding Configuration

# .github/FUNDING.yml
github: [username]

9. Organization Defaults

# Organization .github repository
# Shared templates apply to all repos

10. Verify Community Profile

Repository → Insights → Community Standards

Visual

`.github` Directory Layout

┌──────────────────────────────────────────────┐
│  repository-root/                            │
│  ├── src/                                    │
│  ├── tests/                                  │
│  ├── README.md                               │
│  └── .github/                                │
│      ├── workflows/                          │
│      │   └── ci.yml                          │
│      ├── ISSUE_TEMPLATE/                     │
│      │   ├── bug_report.yml                  │
│      │   └── config.yml                      │
│      ├── PULL_REQUEST_TEMPLATE.md            │
│      ├── CODEOWNERS                          │
│      ├── CONTRIBUTING.md                     │
│      └── SECURITY.md                         │
└──────────────────────────────────────────────┘

Configuration lives in one place. Source code stays clean.

File Discovery

┌──────────────────────────────────────────────┐
│  GitHub looks for issue templates in:        │
│  .github/ISSUE_TEMPLATE/                     │
│                                              │
│  GitHub looks for workflows in:              │
│  .github/workflows/                          │
│                                              │
│  GitHub looks for health files in:           │
│  .github/ → root → docs/                     │
└──────────────────────────────────────────────┘

The location determines whether the file is found.

Summary

Item	Value
Configuration directory	`.github/`
Issue templates	`.github/ISSUE_TEMPLATE/`
Pull request template	`.github/PULL_REQUEST_TEMPLATE.md`
CODEOWNERS	`.github/CODEOWNERS`
Workflows	`.github/workflows/`
Community health files	`.github/`, root, `docs/`
Organization defaults	`.github` repository at org level

Key takeaways:

.github separates configuration from source code. Templates, workflows, and health files live in one directory, keeping the repository root clean.
Discovery is location-specific. Issue templates only work in .github/ISSUE_TEMPLATE/. Workflows only work in .github/workflows/. Placing them elsewhere causes them to be ignored.
Community health files are scanned across three locations. GitHub checks .github/, root, and docs/ in that order. Placing them in .github is the cleanest option.
Organization-wide defaults reduce duplication. A .github repository at the organization level can provide shared templates and health files that individual repositories inherit.
CODEOWNERS must be on the default branch. A CODEOWNERS file on a feature branch is not applied to pull requests targeting main.

Remember: The .github directory is a convention enforced by GitHub’s discovery logic. Files placed there are read by GitHub, not by the build system. Issue templates, pull request templates, workflows, CODEOWNERS, and community health files all live in .github because that is where GitHub looks. Place them elsewhere, and they are ignored.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!

Why the .github directory exists