Over the past two decades, many have welcomed the dawn of a new age. “Finally, the resume is dead,” they liked to repeat, believing the Internet has changed everything—including the way companies hire new employees.

To some degree, the doomsayers were right. The Internet has indeed changed a lot. LinkedIn, online portfolios, even our social media footprints have all become essential to the hiring process. Yet, no one has ever stopped attaching resumes to their job applications. Instead, the above three simply provide the much needed support to the resume.

“…a profession which mostly revolves around creating things would finally get its own version of a portfolio.”

What about GitHub though? If you’re a software engineer, you’ve probably encountered the popular notion that somehow GitHub is your resume now. After all, it only makes sense that a profession which mostly revolves around creating things would finally get its own version of a portfolio. Ultimately, you want to show potential employers WHAT you can do instead of just telling them THAT you can do it. And employers DO love being able to see it.

All right, so in many cases companies are going to ask you for a GitHub profile. But would they hire you based on your GitHub profile alone? The short answer? No, they normally wouldn’t.

On the other hand, GitHub already plays an important role in hiring software developers. Yet, in spite of its undeniable importance as a hiring tool, many writers often overstate its importance in pursuit of a bombastic “next big thing” story.

But what role does GitHub really play in hiring? Is GitHub your resume now? Also, when should you include it in your resume and when not? And if you do, how should you format it? What is the result of the battle of GitHub vs Resume? We’re going to answer all of these questions.

Why do companies ask candidates for their GitHub profiles?

First, a well-maintained GitHub profile shows that you contribute to open source projects. This has always been an attractive quality to hiring companies and they came to see it as a good indicator of whether someone’s a good engineer. In the end, job candidates who take the time to develop their GitHub profile and participate actively in the community can be better evaluated than others.

Second, your GitHub lets them see what you’ve built and how you built it, giving potential employees even clearer idea of your technical skills. After all, GitHub is first and foremost a version control system. As such, it shows how often you’re coding and what code you’re pushing. In the end, the more quality changes you make, the more evidence of your abilities you have to show potential employers.

“In spite of its many advantages, GitHub isn’t the new resume. Similarly to the resume, it has its limitations.”

Third, GitHub allows companies to approach passive talent. These are the engineers who’re not looking for a job at the moment but have all the skills a company is looking for.

Fourth, it helps companies discover excellent problem solvers who, for a variety of reasons, wouldn’t look as good based on a resume alone. In these cases, GitHub allows gifted engineers circumvent the traditional hiring criteria and let their skills reach potential employers.

In spite of its many strengths, a GitHub profile can only provide employers with a limited picture of a candidate’s abilities. Ultimately, GitHub isn’t the new resume. Similarly to the resume, it has its limitations and neither is very useful without context. Why?

What GitHub cannot tell you about a candidate?

GitHub was never designed as a place where programmers primarily exhibit their code to impress potential employers. It’s always been mainly a software development platform, the purpose of which is to make software development more efficient.

“…much of the code you decide to push to your repository doesn’t necessarily say much about your abilities.”

For this reason, much of the code you decide to push doesn’t necessarily say much about your abilities. After all, some programmers use GitHub as a way to backup their code, some want to collaborate, others just want a hosted page for their projects’ docs, etc. The individual projects also vary immensely, based on the context within which you create them. Some of them might be “normal”, well-documented and useful software. Others could be experiments, jokes, or code you could hardly call software. In the end, you have no way of explaining to a recruiter which is which.

The same goes for the usefulness of your individual projects. On the one side, there’s elegant self-documenting code in a project you only made for fun. On the other, you have solutions you had to built under many engineering constraints. This code often doesn’t look good but proves your ability nevertheless. Yet again, you have no way of explaining why does it look the way it does.

Moreover, GitHub revolves around how others perceive you. It doesn’t let you value your work for yourself. For this reason, many great developers might go unnoticed while gifted influencers can get a lot of credit even for the smallest of contributions. In the end, employers tend to view the latter more favourably because the community views them more favourably. In spite of the former being much more impressive, technically speaking.

And most importantly, not all your projects on your GitHub are public. Unless you work in open source development, interviewers won’t be able to see most of your projects. At the same time, if you have a demanding job and a family, you probably have no time to regularly contribute to open source.

Yet, in spite of its shortcomings, you can use your GitHub profile as a leverage to score a great new job. It only takes a bit of effort to make it more self-explanatory and recruiters-friendly.

You don’t have to take sides in GitHub vs Resume. Use both!

A resume gives you complete control over what information you want to show to a potential employer. GitHub doesn’t. Sure, you can pin three of your projects to the top of your profile but that’s it. Still, you can retain some control by including a link to a single project in your resume—instead of your entire profile. All you have to do then is to make sure this project shows you in the best possible light.

How to include a GitHub project on a resume?

Have one project to show. A single project is all potential employers need to see. They’ll rarely go past it anyway. Make sure it’s a good one.

A single project is all potential employers need to see. They’ll rarely go past it anyway. Make sure it’s a good one. Brush up your directory structure. Always follow the Simple Folder Structure Conventions for GitHub projects. By doing this, you ensure that hiring managers spend more than 5 seconds looking at your code. Without delving too deep into your code, your directory structure already shows your sense of architecture and design.

Always follow the Simple Folder Structure Conventions for GitHub projects. By doing this, you ensure that hiring managers spend more than 5 seconds looking at your code. Without delving too deep into your code, your directory structure already shows your sense of architecture and design. Include a README. Make sure the README clearly describes what the application does and tells the reader how to run it, build it, and test it. Consider including screenshots—or even animated gifs—to demonstrate the application’s functionality. Never assume a person reading your code can find their way around by themselves. Reading a quick intro is a thousand times faster than having to figure it out for yourself.

Make sure the README clearly describes what the application does and tells the reader how to run it, build it, and test it. Consider including screenshots—or even animated gifs—to demonstrate the application’s functionality. Never assume a person reading your code can find their way around by themselves. Reading a quick intro is a thousand times faster than having to figure it out for yourself. Add a link to a website or an installer. If it’s a web application project, it should be running online where anyone can see it. In a case of a desktop application, include a link to an installer to make your project look more professional—even if the user will never run it. If you can’t be bothered getting a hosting and a website for your project, know that GitHub has you covered. It lets you create simple static websites and handles release management surprisingly well. You can host your installers directly there.

If it’s a web application project, it should be running online where anyone can see it. In a case of a desktop application, include a link to an installer to make your project look more professional—even if the user will never run it. If you can’t be bothered getting a hosting and a website for your project, know that GitHub has you covered. It lets you create simple static websites and handles release management surprisingly well. You can host your installers directly there. Make your code clean and easy to read. Comment appropriately. The chances are that most people won’t go as far as to read your code anyway but you never know.

In the end, it matters a lot less what the project does than whether you developed it professionally. People who might want to hire you only have limited time. Your adherence to proper form, structure, and all other good coding practices will shine through even if they don’t spent much time looking into your code.

Few more things that interviewers pay attention to:

Use of existing libraries and frameworks. If you don’t have a really good reason for it, don’t include code that re-solves common problems and routines. Show you’re efficient and use open source solutions that are already out there.

If you don’t have a really good reason for it, don’t include code that re-solves common problems and routines. Show you’re efficient and use open source solutions that are already out there. Repeating blocks of code. Does your code repeat itself? If so, find a more elegant solution.

Does your code repeat itself? If so, find a more elegant solution. Tests. Make sure to include a test suite and add a section in the README file to tell them how to run it. If you skip this, you’ll find it impossible to convince a potential employer that you test “manually”. Ideally, you can also integrate your repository with the Continuous Integration (CI) system. This way you can pre-configure all the tests to be run automatically whenever you change something in your code and have the results reported on GitHub.

Make sure to include a test suite and add a section in the README file to tell them how to run it. If you skip this, you’ll find it impossible to convince a potential employer that you test “manually”. Ideally, you can also integrate your repository with the Continuous Integration (CI) system. This way you can pre-configure all the tests to be run automatically whenever you change something in your code and have the results reported on GitHub. How often you code. Your GitHub profile should show consistency. Inexperienced candidates often only have a 1-3 week period of activity to impress recruiters and not much after that. Don’t bother including your GitHub if that’s your case.

Your GitHub profile should show consistency. Inexperienced candidates often only have a 1-3 week period of activity to impress recruiters and not much after that. Don’t bother including your GitHub if that’s your case. Unmodified forks. If your profile contains any number of unmodified forks, remove them. It’s an unnecessary smoke screen that prevents recruiters from seeing your actual contributions. Moreover, it doesn’t say anything positive about your commitment.

ONE MORE THING: GitHub may not be as important in hiring as some would lead you to believe.

Last year, a London based developer who goes under the name of The HFT Guy decided to take a look at the role of GitHub in hiring. After some testing, he arrived at the conclusion that interviewers don’t really look at GitHub: “After a dozen of phone interviews (1 dev per call) and a couple of on-sites (4 to 7 devs per on-site), there was only 1 visit to my profile.”

Sure, his sample was too small to take it at face value. The HFT Guy never disclosed what type of jobs he was applying to. Neither did he say what companies he was approaching.

“Whereas GitHub is still just an optional component of the hiring process, resume remains essential to it.”

Still, his admittedly limited testing shows that the importance of GitHub in hiring varies depending on the company and the role you’re applying for. However, in most cases, you have no way of knowing if a company is going to look at your repositories. For this reason, you may want to polish your GitHub just in case.

Who wins the GitHub vs Resume then? If there ever was any competition, the resume would be the clear winner. Whereas GitHub is still just a supplementary component to the hiring process, resume remains essential to it. If you’ve already brushed up your GitHub then, you might want to take another look at your resume. And make sure it’s equally impressive.