Do you love open source? Does your company have many Github repositories? Do you have a dedicated person keeping all the repos looking nice and complete?

In my experience, many startups lean heavily on open source code that is released in GitHub repositories. There are often multiple repos for the product, for SDKs, for demos, documentation, etc. Despite this huge reliance on distribution of code via GitHub, many of the *basics* of the Github repos are missing – either due to a lack of time/effort, or developers pushing code without knowing all of the characteristics that make for a great GitHub repo.

So, what makes for a great GitHub repo?

Ideally, all your Github repositories should have a:

• License
• Readme
• Code of Conduct
• Contributing guidelines

The Manual stuff

README. We’ve all seen GitHub repos without – or with a very minimal Readme. This is how you tell your users what the repo is all about! Its ok to link to documentation, or to blog posts.. but tell us why you are sharing this code. Brag a little.

License: Each repository in your organization must define a License for re-use. These can change depending on the type of code, or the licenses in code utilized by your repo. This must be defined manually.

Boilerplate

The rest of the repo documentation is what I think of as ‘boilerplate’ – meaning that the same content can be used across all of our GitHub repositories. Just like every node project begins with an npm init or your Kubernetes begins with some YAML, your GitHub repo has boilerplate files that need to appear across all of your organization’s repositories.

This sounds like it might be a pain in the butt – repeating the same files across all of your repos.

The great thing is – it does not have to be a manual process!!

Enter .github

Even if your organization has a lot of repos – you’re unlikely to have a different Code of Conduct across your content, and (for uniformity), you’ll probably have the same contribution rules for all of the repos.

Creating a .github repository in your organization allows you to create ONE CodeofConduct.md and ONE CONTRIBUTING.md, and it will automatically propagates through ALL of your Github repositories!

(In the unlikely chance that one repo needs a different file – any local CONTRIBUTING.md or CodeofConduct.md will override the global organization file)

Simply create a new repository called .github. If you use the web interface, GitHub will walk you through some of the steps. GitHub has some documentation on how to create this repo and the files inside

Code of Conduct

If you create a new file in the web UI called CodeofConduct.md – Github will offer you 2 options for creating your global code of conduct file.

Contributing

You can see the Orkes CONTRIBUTING.md as an example. Give your contributors instructions on how you’d like issues/comments/discussions handled.

Issues As your open source repositories gain traction, you may want issues reported in a standard way across all repos. With the Issues YAML, you can ensure this will happen with the same format whenever anyone files an issue.

You can also have custom funding, support and security vulnerability reporting files across all your repos (see the GitHub Docs for more details).

Team GitHub actions

Does your team use GitHub actions that need a repo to run from? At Orkes, we use Orbit to track how our users are interacting with our social media presence. Orbit creates integrations with many social platforms like Twitter, LinkedIn, Slack and Meetup. These are all run via GitHub actions. Since the .github repo is an “organizational configuration” repository, it’s a great place to run your GitHub actions from.

But we’re not done yet!

IMO, having a uniform code of conduct and contribution guidelines – and a place to host org GitHub actions are *huge* reasons to add a ‘dot github’ repo to your organization. But, there’s one more feature that is pretty killer. If you create a /profile/readme.md file, you are creating an organizational home page that will appear above your repos when visitors land on your organization’s page.

It’s like a readme for your company – you can showcase specific repos, or your companies’ webpage, or – whatever you’d like.

You can see this in action on the Orkes Github page:

We have a link to our docs, our free playground, as well as links to Netflix Conductor (with a star counter for the Conductor repository).

We can add a big logo, add a few links and talk a bit about who we are, and why you should care.

Light/Dark mode

As you can see from the screenshot above, I’m a Github dark mode user. But, different strokes for different folks – some people love light mode. With GitHub styling, you can define a different image for both views, and have your readme (or, well – any document on GitHub) look great for your users.

![orkes logo](lightimage.png#gh-light-mode-only)
![orkes logo](darkimage.png#gh-dark-mode-only)

Conclusion

Making your GitHub repositories look good and making them easy to interact with makes it easier for developers to interact – they know about your company, what the repo does, and if they want to contribute, they know exactly how – since with a ‘dot github’ repository, this is spelled out for every repository created. It also means your developers don’t need to think about Code of Conducts or guidelines – it’s all just taken care of. Making things easier for everyone with less work is should be a north star metric for all developer relations teams – so for that reason alone, you should create a ‘dot github’ for your organization!