Understanding the `.github` Repository

Understanding the .github Repository

📌 What is a .github Repository?

A special repository that centralizes GitHub workflows, templates, and automation for an organization or user account.

---

🚀 Why Use It?

✅ Standardize Issues & PRs → Issue & PR templates (.github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE.md)

✅ Reuse GitHub Actions → Store workflows (.github/workflows/) for all repos

✅ Centralize Policies → CODE_OF_CONDUCT.md, SECURITY.md, CONTRIBUTING.md

✅ Funding & Sponsorship → .github/FUNDING.yml to show sponsor links

✅ Repository Overview → Use .github/README.md as a landing page for organization-wide documentation

---

📊 .github Repository vs Directory

Feature	.github Repository ✅	.github Directory ❌
Applies to all repositories	✅	❌
Contains global actions	✅	❌
Used for single repo config	❌	✅

---

⚙️ How to Set Up .github Repository

1️⃣ Create the Repository

• Go to GitHub
• Name it .github
• Set Public (recommended for open-source projects)

2️⃣ Add Common Files

git clone https://github.com/jdevto/.github.git
cd .github
mkdir -p ISSUE_TEMPLATE workflows

✅ README.md for Repository Overview:

# Welcome to Jdevto 🚀

This repository contains shared GitHub configurations, workflows, and templates used across all Jdevto projects.

## 🔹 Contents
- 📝 Issue & PR Templates
- ⚡ GitHub Actions Workflows
- 📜 Contribution Guidelines
- 🔒 Security Policies

For more details, check out the respective folders!

✅ Issue Template Example:

# .github/ISSUE_TEMPLATE/bug_report.yml
name: "🐞 Bug Report"
description: "Report a bug in the project."
title: "[Bug] "
labels: ["bug"]

Commit & Push:

git add .
git commit -m "📝 Add issue template and README"
git push origin main

3️⃣ Reuse Workflows in Other Repositories

# Reference shared workflow
name: Reuse Deployment
on: [push]
jobs:
  deploy:
    uses: jdevto/.github/.github/workflows/deploy.yml@main

---

✅ Best Practices

🛠 Make it Public for open-source projects
📝 Use Issue Templates to guide contributors
📖 Include a README.md to document organization-wide standards
🚀 Share GitHub Actions to improve CI/CD
🔄 Keep It Updated for better consistency

---

🌍 Jdevto Organization and Example Repository

The Jdevto Organization actively uses a .github repository to streamline workflows, documentation, and automation across all its projects. You can explore their setup in the Jdevto .github Repository.

🎯 Conclusion

The .github repository simplifies workflows, improves standardization, and enhances collaboration across multiple repositories. The Jdevto Organization leverages this approach to maintain well-documented, reusable, and scalable development practices.

💬 Have you used a .github repository? Share your experience! 🚀

Comments

[Nicolas Fränkel]

Good stuff! I used an organization profile years ago and forgot about the .github repo.

[Ben Sinclair]

I'm not sure I understand. Is this repo like a skeleton that Github uses as a template whenever you create a new repository?

[John Ajera]

The .github repository serves multiple purposes.

For example, to define the overview page content of a GitHub organization, you need to create a README.md file inside the .github repository. This file is located in the profile directory and determines what appears on the organization's overview page.

For instance, the overview page at jdevto originates from the file profile/README.md within the .github repository.

[Nicolas Fränkel]

For the record, it doesn't need to be a Markdown file. Asciidoc works as well (and is much more powerful)