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! 🚀
Top comments (4)
Good stuff! I used an organization profile years ago and forgot about the
.githubrepo.I'm not sure I understand. Is this repo like a skeleton that Github uses as a template whenever you create a new repository?
The
.githubrepository serves multiple purposes.For example, to define the overview page content of a GitHub organization, you need to create a
README.mdfile inside the.githubrepository. This file is located in theprofiledirectory and determines what appears on the organization's overview page.For instance, the overview page at jdevto originates from the file
profile/README.mdwithin the.githubrepository.For the record, it doesn't need to be a Markdown file. Asciidoc works as well (and is much more powerful)