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)
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
.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 theprofile
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.For the record, it doesn't need to be a Markdown file. Asciidoc works as well (and is much more powerful)
Good stuff! I used an organization profile years ago and forgot about the
.github
repo.