GitHub has many special repositories. For instance, you can create a repository that matches your username, add a README file to it, and all the information in that file will be visible on your GitHub profile.
You might already be familiar with the
.github directory you'll find in many repositories. The
.github directory houses workflows, issue templates, pull request templates, funding information, and some other files specific to that project.
But another special repository you can create is the
.github repository. It acts as a fallback for all of your repositories that don't have an actual
.github directory with issue templates and other community health files.
For example, say I have a repository named
.github with generic bug report and feature request issue templates. And say I create another repository called
new-project, but I don't add a
.github directory with issue templates to it.
Then if someone goes to the
new-project repo and opens an issue, they'll be presented with an option to choose from the generic templates already in the
Similarly, if I add a code of conduct to my
.github repository, it will be shown across all my repositories that don't explicitly have one.
Just note that the files inside a repository's
.github directory will be chosen over the ones in the
.github directory. For example, if my
new-project repo has a
.github directory with a feature request issue template inside, that will be used instead of the generic feature request template from the
Let's see how this special repository works in action.
How to Use .github on Personal GitHub Accounts
Creating this special repository is as easy as creating any other repository on GitHub. So go ahead and open GitHub on your web browser and create the repository like this:
After you're done creating the repository, you can start adding files to it. The first file I will add is a bug report issue form. I am not going to go over the details of creating an issue form in this article, but you can have a look at a previous article I wrote about GitHub Issue forms.
I am also going to create a feature request form.
I am also going to be adding a pull request template.
The last file I am going to be adding is a code of conduct – but this is going to be on the root of the repository. Despite that, this will work as intended (code of conduct files are usually kept on the root of the repository). Note that I am using the Contributor Convent convention.
We can add more files like funding information, contributing guides, and much more. For more information, you can look at the GitHub docs regarding community health files
.github repository in action
My blogs repository doesn't have any issue templates, code of conduct, or any other file except for the markdown files of my blogs and a README. So it's the best repository to test upon if this feature is working or not.
I can already see the code of conduct appearing here:
If I try to create an issue, I am presented with the templates as well:
This will also work when creating a pull request.
How to Use the .github Repository for an Organization/Public Account
.github repository on an organization account works just like the
.github repository on a personal GitHub account – except there is one difference.
Organizations can also have profile READMEs that show up on the organization page on GitHub. This README resides on the
profile directory of the organization's
.github repository. To demonstrate this, I will quickly create a demo organization.
When creating the
.github repository for an organization, you should get this message:
Also when adding the profile README to
profile/README.md, you should be getting this message:
Now, I am going to add some content to that README file and commit it. When I visit the organization's home page this is what we should see:
I hope you now know what the
.github repository does. You should also know how to set up default community health files for your repositories and a profile README for your organization.
Feel free to reach out to me on Twitter and have a nice day 😃
- GitHub Documentation on Community Health Files
- My test organization's
- Contributor Convent
- Article on getting started with GitHub issue forms
I am currently working on a project called DevKit which is a PWA that will house developer tools in one single application and provide ways to get your work done quickly. Do check it out at https://www.devkit.one/.