As a maintainer of a repository, it’s in your best interest to automate processes as much as possible. The CODEOWNERS file is one of those tools to help with automating processes.
I decided to write a post about the CODEOWNERS file after reading this comment from one of our awesome Octerns, Divyansh (@diivi), in a pull request (PR) where I added the file.
A CODEOWNERS file in GitHub is a special file used to specify who reviews and maintains specific files or directories in a repository. It helps with identifying code ownership and who should be notified when pull requests are made to those repositories.
For example, in this particular CODEOWNERS file there is the @open-sauced/engineering team.
When someone creates a PR for that repository, that team is automatically added as a reviewer.
This is really handy because you don’t need to go and manually add reviewers, and when it’s a PR from an external contributor, they can’t add reviewers so this is super useful for them and can avoid comments like, “Can someone review my PR?”
Another nice feature of the CODEOWNERS file is that it can be used as part of branch protection.
To enable this, go to the Protect matching branches section of a branch protection rule, and ensure the Require review from Code Owners option is checked.
One other thing to note is if you have permanent branches aside from main, like beta, dev, or whatever your team calls it, they can have different individuals and teams in those branches CODEOWNERS file.
How to add a CODEOWNERS file to your project
The CODEOWNERS file is a special file that can reside in the root directory, in the .github directory or the docs directory (if you have one).
The .github folder might not exist in your project if you haven’t added other GitHub automated processes like GitHub Actions, pull request templates, or issue templates.
Also note, GitHub looks for the first CODEOWNERS file it finds, searching first in the root directory, then the .github directory, and finally, the docs directory (if it exists).
You can add individual GitHub users, a team, or a combination of them to a CODEOWNERS file.
A nice feature of adding or making changes to a CODEOWNERS file in a pull request is that GitHub validates it, letting you know if you are adding a non-existent user or team.
If you don’t already have a CODEOWNERS file file in your repository, I encourage you to add one. Let us know if you have any questions about this or other maintainer-related issues.
Stay saucy peeps!
If you would like to know more about my work in open source, follow me on OpenSauced.
Top comments (26)
Do you know whether or not this is something that can work if placed in the specially named .github repository to serve as a default for all repositories that you own that don't otherwise have it? The way you can with templates for pull requests and issues, as well as contributing guidelines, security policies, etc.?
That’s a great question. I’m not sure, but I feel like it would.
The only problem is GitHub grabs the first one it finds so there’s no merging or inheritance for CODEOWNER files, so if it was global, every repository would always have the same code owners.
If it works, then I think it would probably work the way other stuff in that repository works, global across all repositories you own, but if an individual repository also has it then the local one takes precedence. I might just try it. I don't currently have a CODEOWNERS file in any of my repositories. So as easy to try in my .github repo as in any other.
Awesome. Let me know how it goes and I can update the article if you can override that global one.
I just tried it from my .github repository. It doesn't work from there at all. So it looks like it is limited to configuration within a single repository.
Oh well. Thanks for giving it a go!
A simple file, but very useful!
Merci Thomas!
This is supported by most big VCS cloud platforms, like GitLab, etc.
I think only Bitbucket doesn't support it directly - but there's a free plugin in the Atlassian marketplace which does the same thing.
Yeah, I knew GitLab supported it, just wasn’t aware of the Atlassian plugin. Thanks for sharing!
Really nice article, Nick :)
Perhaps you could add a paragraph that explains how to add path-based rules (or other patterns) to CODEOWNERS. It is very useful for mono-repos and scenarios, where several teams manage and own different parts of the code, like the Infra team owns the
/infradirectory with Terraform code, while the app team owns the/srcdirectory with the application code.Thanks for the kind words, David. This was more of a primer, but happy to add this to make it a bit of a deeper dive. Thanks for the feedback!
Great article @nickytonline !
I was first introduced to the Codeowners file a few years ago with freeCodeCamp's main repo
github.com/freeCodeCamp/freeCodeCa...
But now, I am thinking of adding it to other repos I help maintain :)
Noice!
Excellent article! Such an important aspect of DevSecOps. We use arnica.io to automate our code owners management. Check it out: arnica.io/blog/what-every-develope...
Amazing! I'm glad to know people learned something new because I shared what I didn't know!
I just learned about this file a few weeks back from @danieltott! I haven't had time to explore, so thanks for sharing, @nickytonline 🙌🏼😄
This is very useful, thanks for sharing your knowledge with us!
Glad you found it helpful Emmanuel!
Nice, I didn't know about this file but this is great for automating the reviewer process so the specific code owner is notified. This is great, thanks!
Glad you found it helpful!