This is your brain. This is your brain on computers.

Using GitHub to Build a Portfolio (2020 Ultimate Guide)

If you’re in school, fresh out of school with a brand-new diploma, self teaching yourself programming, or looking for ways to change your career path, one of the single best ways to get yourself noticed is through a portfolio of your work. Over time, through school assignments, coursework, and your own personal projects, you can amass a collection of projects to show off in your portfolio. Fortunately, using a platform like GitHub to build a portfolio is free, easy, and teaches you critical skills that you can apply for yourself and an eventual employer.

GitHub is a distributed service that allows for remote Git repositories. This enables you to host your repositories in an environment that allows you to share your code with the public and allows others to contribute to your project in parallel.

There’s no sense in hiding what you know and what you’ve built just because you don’t think you or your projects aren’t “good enough.” Imposter syndrome can be a tough thing to break through.

We’ve personally interviewed hundreds of candidates and are continuously impressed by people who come prepared to discuss (and show off) projects they maintain in a public platform like GitHub. Even better, some candidates spice up the presentation of the projects by using specific web pages to describe what the project is, how to use it, and why it exists.

Not only does a public portfolio give you some much-needed ammunition during an interviewing process, but it also gives you experience with tools that are used in the real world and just might get you noticed by others in the community. There’s literally no downside. You gain real world skills, help yourself during the job hunt, and have the potential to join teams in the open source world.

And all of that is completely free. Just do it.

Install & Learn Git

As is implied in its name, GitHub requires the use of Git.

Git works natively on Windows, Mac, and Linux. When using Windows, you’ll most likely be using the tools included in the Git for Windows initiative (Git BASH, Git GUI, and Git Shell Integration). Mac and Linux have native command line support.

To get started, go download Git by finding the link for your operating system.

For example, with Ubuntu, you’d use: apt install git. You might need to augment this with sudo if your setup requires root to install software.

Note that Git is, by default, purely a command line tool. If you’re interested in using a user interface to manage your Git repositories, check out our tooling guide for some suggestions or our massive Visual Studio + Git guide. You can also check out the official Git GUI page.

The rest of this guide assumes that you’re on Windows, but the process is identical regardless of your operating system.

Don’t know how to use Git? Take a look at our Getting Started with Git guide so that you’re set up for success and ready to contribute to projects with confidence.

Save Your Assignments & Coursework

Remember all those weird programming assignments that you had to finish during your classes? Maybe you had to write a binary search algorithm or a basic version of a text-based poker game. You probably didn’t think you would ever need them again. Don’t throw away your previous work just because it was annoying and barely finished the night before it was due (apologies to any non-procrastinators out there).

What about the code you wrote and projects you finished while going through Khan Academy, Coursera, and Pluralsight?

Maybe you’ve completed our multiple guides to becoming a software engineer without a degree and want to save everything you created during that process.

Having previous projects that you or a team completed can work as filler for your portfolio. It might not be the highest quality work, but it does at least prove that you have some academic experience, understand the basics of source control (using GitHub requires that), and care enough to publish your previous work publicly.

In short, find all your old coursework, create locally Git repositories, and commit them.

Start Experimenting

Don’t have any coursework or don’t have enough to fill out a portfolio? No problem. After all, having a degree is not a requirement to become a software developer.

Go complete our guide to becoming a software developer first. Then come back here and start building more personal projects on top of the ones suggested in that article. In fact, you should probably build more even if you have a lot of school assignments in your collection.

A big part of the satisfaction behind software development is the knowledge that you created something. Not only do you get something that you can call your own, but you also gain critical skills related to problem solving and thought experiments.

Hands on experience is almost always the best way to improve your skills. Academic knowledge can get you started, but having something physical (or in this case, digital) to touch, feel, and manipulate gives you real world experience and an eventual sense of accomplishment when you release your product to the world.

Did you know?

Software engineering is more than just programming. You need to understand the best practices around your project’s source control, build/release process and cadence, project management, team collaboration, and testing strategies. These are skills that are rarely discussed during the completion of Computer Science and Information Technology degrees. Often the only way to obtain them is through self learning.

Start by checking out our big list of the best programming tools that every developer should get to know. We don’t suggest you install every tool on that list, but it’s good to keep the list in your back pocket throughout your journey. Remember to customize your workspace and download productivity-boosting extensions for your development environment.

Like any old coursework that you have, track and commit each of these projects to Git.

Begin With Small Projects

Keep your first experiments small. You don’t have to be stuck with “Hello World,” but you also shouldn’t immediately try to create the next billion dollar application. Don’t abandon projects mid-stream unless absolutely necessary. You should see every project through to the finish or, at the very least, to a point where it appears finished.

Of course, you have to define what “finished” means to you and to that specific project. You’ll quickly learn that many applications are never truly finished. You make something “good enough”, ship it, and move on.

Try making a list of simple games to create. Keep it text-based. Don’t jump directly to graphical games. It’s amazing how many fundamentals can be reinforced in something like Poker, Blackjack, or Dungeon Crawlers.

Build a Simple Website

Basic, static websites are extremely easy to build. You’re not looking to make the next Facebook. All you need to do is prove that you understand the fundamentals of HTML, CSS, and maybe some basic JavaScript. You don’t need anything other than a basic text editor and modern browser to get started.

Create an index.html file to play around. Think back to the classes you took in college or on Khan Academy, Coursera, and Pluralsight. Don’t feel bad if you have to reference those materials again. Software development is a constant struggle between remembering esoteric syntax and reading through documentation.

Start with something like this:

<!DOCTYPE html>
<html>
  <body>
    <h1>A Heading</h1>
    <p>A paragraph with some text</p>
  </body>
</html>

Yes, that’s not a very flashy layout, but that isn’t the point. Just getting your hands on the keyboard, typing something out, and seeing the result of it is positive.

Try to think and build incrementally. It’s fine to have a long term vision for your project, but it isn’t possible to build the end state immediately. You’re going one header, paragraph, and image at a time. Eventually you’ll have something really cool.

Work through tutorials online. Reference back to the courses you completed (you did complete them, didn’t you?). You’re on a roll.

Play with .NET Core

Websites are fun to build, but sometimes building them doesn’t feel like you’re programming.

Fortunately, the barrier to entry to use compiled languages has been drastically lowered in the last couple of decades. Software development kits (SDK) have progressed to the point where everything is packaged up conveniently for you to get started.

Microsoft has an awesome cross-platform (Windows, Linux, Mac) framework that you can use to learn C#, Visual Studio, and Visual Studio Code. We recommend you work through the C# sections of Pluralsight shown in the previous sections. You can also use this time to see if you like the built-in Visual Studio + Git interface. Some people prefer it over the command line.

Start by downloading the .NET Core SDK. As of this writing, the current version is 3.1.101. Microsoft regularly updates this, so make sure to check back and get the latest updates. If you’re using Visual Studio, its own automatic updates may also bring in dependencies like .NET Core automatically.

Microsoft website to download .NET Core SDK.

Spin up your first console application to play in. Treat this as a sandbox and don’t be afraid of trashing it. Again, you’re just experimenting.

$ cd <my_project_directory>
$ dotnet new console -o HelloWorld
$ dotnet run
Hello World!

That’s your first C#/.NET application. OK, so you didn’t do much, but that’s just the beginning. Now it’s your turn to start playing around. As mentioned before, you don’t need any fancy development environments yet. When you feel that you’ve outgrown Notepad (and that will happen quickly), check out Notepad++, Visual Studio and Visual Studio Code.

Remember, you’re building incrementally. The whole point is to get your fingers going and your mind flowing. Eventually you’ll have a collection of projects to present on your portfolio.

Push Repositories to GitHub

This is the fun part. That’s not to say that everything leading up to this moment wasn’t also fun but now you get to show your skills to the rest of the world.

Create an Account

Good news. GitHub can be free to use. We say “can” instead of “is” because there are many types of plans offered, and some of those plans require monthly payments. Fortunately, for you as a hobbyist, you don’t need to pay.

Create an account on GitHub and start with a free plan to get enough features on your path towards a successful public profile.

Set Up Your Profile

It’s not enough to just create your account. You have to advertise, sell, and brag about yourself. You don’t have to give away the keys to your house, but it does help to make a profile with some basic descriptions of yourself and your related work.

With that said, go to your profile page to get started.

Profile Details

Find an interesting profile avatar that will be used across GitHub when you contribute to repositories. It doesn’t have to be a picture of yourself. The author of the profile below is a big fan of Metal Gear, so that explains the example profile picture.

Fill out your bio to talk about who you are, what you primarily work on, and where you currently work (if any). Just have fun with it Brag about yourself. You can also link other users and organizations on GitHub with which you might be affiliated.

If you have a website that you want to direct viewers to such as a StackOverflow profile, a résumé, or just a personal site that you’ve built for yourself, place that in the profile URL box.

GitHub profile page describing bio/URL to enter.

Private Contributions and Job Notifications

Don’t move on yet. There’s more near the bottom of the main profile screen.

Click to enable “Include private contributions on my profile.” As it describes, this will allow your activity feed to show private activity as well as public. You definitely don’t want to be penalized because you mainly contribute to private repositories. We strongly suggest that you make all of your repositories public unless that absolutely isn’t an option.

If you’re in the job market or just want to keep yourself open to opportunities, check the box to make yourself “Available for hire.” When you check various sections of GitHub, you’ll see job placement advertisements relevant to you.

GitHub profile page highlighting options to select

Profile Notifications

With your main profile out of the way, move on to the “Notifications” tab. This is where you control all the ways in which you can be notified of activity happening on GitHub.

When you start getting more active in GitHub, it’s important to stay on top of anything that may directly affect you.

Maybe someone is asking for your help with using your project. Or maybe you’ve left a comment on another repository and someone is responding to you. Regardless, staying engaged increases the chances of people liking your contributions and following your future progress.

While the notifications settings is largely up to you and your discretion, we suggest the following at a minimum:

  • Email, web, and mobile notifications for anything in which you’re “Participating”
  • Email, web, and mobile notifications for anything you’re “Watching”
  • Email notifications for comments on issue and pull requests
  • Email notifications for pull request reviews and pushes

Experiment with which type and level of notifications works for you and your projects. Again, this is up to you. The trick is to stay engaged regardless of how you’re notified.

GitHub notifications UI showing opt-ins.
GitHub notifications UI showing opt-ins.

There are a lot of other settings in your profile that you can play with. Many of them are related to security, billing, and other non-engagement related configurations. Take your time to look through everything in case you see something that piques your interest.

Create a Repository

OK, your profile is good to go. Now it’s time to get your code out there.

Click the + symbol in the upper right after logging in to GitHub. Click New repository.

GitHub create repository selection

Repository Name

First, you obviously need to name your repository. You can change the name later if you end up changing your mind in the future. After renaming, GitHub does redirect requests from the old to the new name. But to reduce confusion, you should update all your remotes in your local repositories.

GitHub create new repository name

Repository Description

Next, you need to add a good description of your repository. While GitHub does mark it as optional, we consider it to be required. This is mainly because a good description goes a long way to building interest, traction, and eventual collaboration in your projects.

GitHub create new repository description

Public or Private?

Always mark your repositories as public unless you absolutely can’t because of proprietary information. If it’s private, no one can see or contribute to it.

GitHub create new public repository

Create README, gitignore, and License

Initialize a README file unless you already have one in your local repository project. You can design the README using markdown. Don’t skip this step even if you’re feeling lazy. Like a good description, a README is critical to gaining traction in your project.

While you may know everything there is to know about your code, keep in mind that strangers have never seen your project and will have no idea where to get started. The README file can explain to people why the repository was created, where to get dependencies, how to build the project, how to use the code, and how they can contribute properly.

Optionally select from a list of prebuilt .gitignore files based on your project specifics.

We suggest you select a permissive license so that others can take what you’ve built and build upon it without having to worry about legal issues. Obviously this is entirely dependent on your project and its stakeholders. But if you have any say over it, more permissions usually equals more use.

GitHub create repository to select readme and license file

Social Share Image

Social media is unavoidable if you want to share something on the Internet. And since the point of this guide is to share your projects, at some point you’ll have to use social media. Fortunately, GitHub has a feature to choose an image for your repository to display when sharing links to it on something like Facebook or Twitter.

GitHub social preview example

Enable Wikis and Issues

In your repository, click the Settings tab in the upper right. You’ll need to make sure certain features are turned on for your repository.

First, enable “Wikis” to promote crowdsourcing of your documentation. You can obviously start the documentation by creating a good README with supporting articles built up over time. You should also let others edit and contribute to the wiki.

Next, enable “Issues”. There’s really no reason to disable this. You can use it to track problems that you want to tackle in your project. Others can use it to report problems they’ve found while trying to use your code. Unfortunately, many people abuse this system by using it like a forum to ask a question or have a discussion. But as the owner of the repository, you can clean that right up.

GitHub repository features with suggestions

Use the Community Checklist

One more thing before you’re done configuration your repository. Click the “Insights” tab and then the “Community” menu button to see how your repository fares against the GitHub standards. You’ll see a checklist which grades the engagement potential of your repository.

  • Add a description, README, and license file as we’ve discussed
  • Create a code of conduct describing how you want contributors to behave when engaging in your community
  • Write guidelines to support others when contributing
  • If you find that your repository becomes popular, you might want to create issue and pull request templates to avoid having messy contributions
GitHub repository insights showing community checklist

Finalize the Look

Make sure the description looks OK on the main repository screen. Clean up your project’s folder structure, file names, and overall look. By making it look somewhat tidy, you’ll at least give the impression that you care enough to be organized.

Trust us, this is super important to some interviewers. There are far too many developers out there that are chaotically disorganized to the point of being detrimental to their team.

And finally, finish that README. Again, don’t skip it. We can’t stress this enough. Many viewers will bounce immediately upon seeing a vacant or unexplained repository.

If you take the advice above, you should have an attractive and professional repository. You won’t just be “faking it until you make it.” You’ll have actually made it!

GitHub repository example with best practices

Add a README & Permissive License

Don’t worry if you forgot to add a README or license file on creation of the repository from the GitHub UI. You’ll still have the ability to add them when needed.

At the bottom of your repository’s file viewer, you’ll see a button to “Add a README”. Click it and start the process.

Adding a license file isn’t as intuitive. GitHub, are you listening? You should add a button just like the README feature.

Since there isn’t a nice convenient button, instead you’ll have to click “Create new file” and then name that file with “license” in it. Once GitHub detects that word, you’ll see a “Choose a license template” button appear. Click it to begin the process of adding a license.

GitHub create readme and license dialog
GitHub create license file dialog

Clone Remote to New Local Repository

If this is a new repository with no local copy, you’ll need to clone it locally before you can start contributing to it.

In the GitHub repository viewer, find the link in the upper right of the file viewer that says “Clone or download”. Under it, you’ll see a URL that you can use to clone the repository or add as a remote.

GitHub repo UI showing where to get repo URL.

Change to the directory that stores your repositories locally and then clone your remote repository.

$ git clone <GitHub remote URL>

Confirm the clone was successful.

$ cd <repository_name>

If successful, you can start contributing to your local repository immediately.

To push any commits that you have locally, use the following commands making note of the name of the remote repository to push against and the branch in which you want your changes included. If asked for credentials, you’ll need to use your GitHub username/email and password.

$ git push [remote] [branch]

# Example pushing the master branch to the origin remote
$ git push origin master

Push Existing Local Repository to Remote

But what if you already have a local repository? How do you get that into GitHub?

If some of your projects already have local repositories setup on your developer machine, then you will need to add the new GitHub repositories as remotes.

Just like when cloning a new repository, look for the remote URL in the upper right of your repository’s file viewer.

GitHub repo UI showing where to get repo URL.

Now add the remote repository and name it “origin”. It doesn’t have to be named that, but it’s standard and matches what you would get if you used the git clone approach.

$ git remote add origin <URL to GitHub repo>

Confirm the remote was added properly.

$ git remote -v
> origin <URL to GitHub repo> (fetch)
> origin <URL to GitHub repo> (push)

To push any commits that you have locally, use the following commands making note of the name of the remote repository to push against and the branch in which you want your changes included. If asked for credentials, you’ll need to use your GitHub username/email and password.

$ git push [remote] [branch]

# Example pushing the master branch to the origin remote
$ git push origin master

Build GitHub Pages for Repositories

What good is a portfolio if you don’t have a way of showing it off? Sure, GitHub is great at storing the code, but you can’t just link to your GitHub profile and expect people to wade through your collection.

GitHub Pages to the rescue. It’s basically a way of linking a public site against your repository (or your user account) and maintaining those sites using markdown.

Using that approach, you don’t have to worry about getting a host and domain nor do you need to worry about knowing HTML and CSS (though those skills are easily learned).

User Site versus Project Site

Everyone gets a single user GitHub Page which is published from a repository that is dedicated to that page. This page is typically used to showcase you, your abilities, and a collection of your projects. Treat this like a landing page dedicated to you. You can brag about yourself and your credentials or just make a good-looking listing of all your repositories and their GitHub Page.

Project sites are infinite and only limited by the number of repositories attached to your GitHub account. Use these to spruce up the public persona of your project to attract even more attention. Sure, a README file is good, but it’s usually just text. With a GitHub Page, you can build a full-blown web-based experience to show off your project and its use cases.

To build your user site, you’ll need to create a repository named <username>.github.io so that GitHub knows this repository exists only to be published for your user GitHub Page. You would then access this page at https://<username>.github.io unless you’re using a custom domain.

GitHub create user page repository.

To build a project site, you can use your existing project repositories, but you’ll need to enable GitHub Pages for each individual project.

Let’s dig in to enabling GitHub Pages for both your user repository and all your project repositories.

Enabling the Site

Go to the repository for which you want to set up GitHub Pages. Click Settings in the upper right. Yes, the same Settings that you used previously in this guide to enable Wikis and Issues.

Scroll down to the GitHub Pages section to select the source of your GitHub Pages code and a prebuilt theme to use. The theme isn’t required if you’re good with CSS and want to customize the layout exactly to your liking.

GitHub Pages options

To keep your GitHub Pages source isolated from the rest of your project code, we suggest you either create a separate branch dedicated to the upkeep of the GitHub Pages source or a folder within the master branch dedicated to the same purpose. By default, GitHub will suggest a /docs folder, but you aren’t bound to that.

GitHub pages source chooser

As for a theme, it’s a very personal choice that only you can make in the end. If you’re good with CSS, you might want to skip a theme altogether and customize to your heart’s content.

Experiment with the prebuilts to see if they meet your needs. Some of them are really well-made and don’t require any further action from you after selection.

GitHub Pages template chooser

Building the Site

So you’ve enabled GitHub Pages for you and your projects. Now what?

Create some markdown files for your pages! Don’t know how to use markdown? Here’s a quick guide to mastering it.

Need some tools to help you write markdown in a more friendly way? Check out this Visual Studio extension or this awesome standalone markdown editor. Typora’s website is a little weird (the landing page is almost entirely blank), but scroll down and you’ll find what you need.

GitHub Pages works by publishing static files in whatever location you identified as the source for the site. By default, the README file that we’ve pestered you to create (you did create it, right?) is used as your site’s index. When loading the main page, the README file will be presented. Any other markdown files that you create in the source folder will also be rendered by GitHub Pages.

This means you can create a main page, an about page, a contact page, and much more depth depending on your project’s needs. This also means that you can’t use server side languages like PHP or Ruby to maintain content on your GitHub Pages.

In the most basic terms, GitHub Pages uses an engine that converts markdown md files to html format automatically. You don’t need to write any HTML for it to work.

However, that does mean that you need to be aware of the file extension being changed when deployed to the site. This won’t affect links that you create between files because the GitHub Pages engine will do the translation of links for you.

For example, creating links to the following examples of pages will still work because of the automatic translation.

index.md --> index.html
contact.md --> contact.html
about.md --> about.html

GitHub Pages Tips

  • At the very least, create a good README to act as the index
  • Create pages dedicated to contacting you, your social profiles, codes of conduct, contribution guidelines, and details of how to build and use your project
  • Look at high profile examples to get some more ideas
  • If you’re feeling fancy, create 404 pages for your GitHub Pages sites to redirect users from content that doesn’t exist
  • Read through the detailed documentation for more help
  • Use your user site to build a landing page dedicated to you and your projects

Keep Going

That’s a lot of work to get going, but the good thing is that you only have to do it once for your account.

Creating a GitHub account and going through your profile and repositories to make the suggested adjustments will have a net positive effect on your relatable nature as a developer. You’ll come across as a professional, competent, organized, and self-starting individual. In the ocean of software developers, companies are becoming increasingly interested in candidates that take the initiative to self-start their path to success.

If you made it to the end of this guide, you’ve potentially added the following skills to your toolbox:

  • Source control and Git specifically. This is a required skill for software engineering.
  • Distributed source control and GitHub specifically. This is a super useful skill in team based environments.
  • Documentation and markdown specifically. This is a lost art in many corners of the software industry.
  • Confidence to create your own projects and publish them to the rest of the world.

It’s on you now to take things to the next level. You’ve got the skills and the confidence to fill out your profile with projects.

Remember, they don’t have to be world-changing to be presented in your portfolio.

Show that you have initiative. Show that you’re confident. Keep going. Good luck.

Justin Skiles

Justin Skiles

Justin has been developing enterprise application software for over 10 years primarily using Microsoft stacks, Azure, and various open source tools. He has most recently been trying his best as a Manager and Director of Software Engineering in the health care industry.

Share the Knowledge

Share on facebook
Facebook
Share on twitter
Twitter
Share on linkedin
LinkedIn
Share on pinterest
Pinterest
Share on facebook
Share on twitter
Share on linkedin
Share on pinterest

Follow our updates

JOIN OUR SUBSCRIBERS

GET FREE UPDATES

Keep Exploring. Choose Your Path.

Be a Better, Smarter You

With our in depth guides, you’re bound to be setup for success.

Our experts have been collectively developing software for over 20 years.

We find the best tools and direct you to them so that you don’t have to.

JOIN THE CONVERSATION

Get the latest ultimate guides, tutorials, and advice to level up your skills.