DEV Community

John Ajera
John Ajera

Posted on

Understanding the `.github` Repository

#github #automation #devops #cicd

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
Enter fullscreen mode Exit fullscreen mode

✅ 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!
Enter fullscreen mode Exit fullscreen mode

✅ Issue Template Example:

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

Commit & Push:

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

3️⃣ Reuse Workflows in Other Repositories 

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

✅ 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)

Collapse
 
nfrankel profile image
Nicolas Fränkel •

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

Collapse
 
moopet profile image
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?

Collapse
 
jajera profile image
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.

Collapse
 
nfrankel profile image
Nicolas Fränkel •

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