GitHub has many special repositories, like the README in your profile. You can get creative and add all sorts of helpful information there.
Another special repository is the .github repository. This might remind you of the .github directory in repositories which house workflows, issue templates, pull request templates, funding information, and some other files.
The .github repository does something very similar – it acts as a fallback for repositories that don’t have these types of community health files.
For example, say I have a bug report and feature request issue template in my .github repository. Then, say, I create a repository called new-project but I don’t add any issue templates to it. Then, if I try to create an issue in that repository, I will be presented with the option to choose from the issue templates I had created in the .github repository.
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 if a repository has those files, they will be used instead of the ones in the .github repository.
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
The .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
The .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 be getting 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 😃
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/.