.github Folder

The .github directory is a special directory in GitHub repositories used to configure and customize GitHub-specific features. Here’s everything you need to know about its purpose, structure, and best practices:
Author

Benedict Thekkel

✅ Overview: What is .github/?

The .github/ folder is used to:

  • Store community health files like issue templates, pull request templates, and contribution guidelines.
  • Configure GitHub Actions workflows.
  • Customize repository behavior and interactions.

You can place it:

  • Directly in a repo (e.g., my-project/.github/)
  • In a dedicated public repo like .github at the organization level to share templates across multiple repositories.

📁 Common Structure of .github/

.github/
├── workflows/             # CI/CD workflows (GitHub Actions)
│   └── main.yml
├── ISSUE_TEMPLATE/
│   ├── bug_report.md
│   └── feature_request.md
├── PULL_REQUEST_TEMPLATE.md
├── CONTRIBUTING.md
├── CODEOWNERS
├── dependabot.yml
├── FUNDING.yml
├── SECURITY.md
└── SUPPORT.md

🛠️ Files Explained

1. workflows/ (CI/CD via GitHub Actions)

Defines automated workflows like tests, deployments, linting, etc.

# .github/workflows/test.yml
name: Run Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.12'
      - run: pip install -r requirements.txt
      - run: pytest

2. ISSUE_TEMPLATE/

Adds structured forms for users to submit issues.

  • bug_report.md
  • feature_request.md

You can also use a config file:

# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
  - name: Chat with Support
    url: https://support.example.com
    about: Reach out to us directly.

3. PULL_REQUEST_TEMPLATE.md

Standardizes PR submissions (e.g., checklists, summaries).

## Description

## Checklist
- [ ] Tests added
- [ ] Docs updated

4. CONTRIBUTING.md

Guidelines for external contributors. GitHub will link this when users open PRs or issues.

5. CODEOWNERS

Defines who reviews which files automatically.

# All JS files must be reviewed by @frontend-team
*.js @frontend-team

6. dependabot.yml

Automates dependency updates.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"

7. FUNDING.yml

Adds a “Sponsor” button.

github: ['yourusername']
patreon: yourpage

8. SECURITY.md

Instructions for reporting security vulnerabilities.

9. SUPPORT.md

Links users to support channels rather than opening issues.

🧠 Tips and Best Practices

Area Best Practice
Templates Use clear, concise prompts in issues/PR templates
GitHub Actions Break down workflows into small, reusable jobs
CODEOWNERS Keep ownership specific (avoid *)
Community Health Files Use organization-wide .github repo to centralize templates
Automation Combine Actions + Dependabot for full CI/CD and maintenance

🔗 Reference Docs

Back to top