Part of any project I do, private or open-source, is to set up a version control system and securing access to that version control system. In addition, it is always a high priority for me to make sure that the secure access follows best common practices on security, as it is protecting work that I am doing. Using Git as my version control system of choice, and GitHub as the open source repository host of choice, it made logical sense to make my website platform of choice GitHub Pages3. As such, in setting up this website I needed to make sure I had Git1 and more specifically GitHub 2 setup, and setup securely.
This article details the actions and choices I made in setting up my access to GitHub for my blog. It details how I followed the GitHub Pages instructions for creating a personal website and creating a personal repository on GitHub to achieve that. Then it describes the two modes of accessing GitHub, SSH and HTTPS, and why I chose SSH. Finally, it provides detailed notes on how I generated a SSH keypair specifically for GitHub, and configured both my local Git and the remote GitHub to use them.
Getting Started With GitHub¶
There are many good articles out there on how to install Git for different operating systems, so I feel it is safe to assume that anyone reading this can do the research needed to install Git for their operating system. Setting up access to GitHub is even easier, as the folks at GitHub have provided excellent instructions. Start the setup by simply going to the GitHub Home Page and following their instructions.
The pivotal part is that to start using GitHub in a serious manner, you need to authenticate
yourself to the GitHub servers. Thus, the workflow will either allow you to login, if you
already have an account, or create a new account, if you don’t have an account. Having already
dealt with a couple of open source projects, I logged on to my account
After I logged in, the browser deposited me on my home page. From there I was able to see any projects that I had either contributed to or filed an issue against. Just starting in my Open Source journey, the contents were only a couple of projects that I had filed issues with. Prior to this point, I had no need to authenticate my Git client with GitHub as I was just downloading from public repositories. Having done some research on GitHub Pages, I knew that setting up my own website with GitHub would require me to create my own repositories. As such, my next task was to create that repository.
Creating My First GitHub Repository¶
The GitHub Pages home page has a really simple formula on their
webpage for setting up personal webpages. The first step is pretty easy: make sure that
that the name of the repository is my GitHub user id (in my case
jackdewinter) followed by
.github.io. When the creation of my repository finished, GitHub deposited my browser
at the base of my new repository:
jackdewinter/jackdewinter.github.io. The remaining steps in
the formula dealt with cloning the repository, defining a sample
index.html file for the website, and pushing that code back to the repository. While I was
familiar with those concepts, I wasn’t shy about checking back with the
Git Basics documentation
on the Git website when I forgot something. From there I was able to find the correct helper
article on what I need to accomplish within 2-3 clicks.
In GitHub, unless you mark a repository as private, everyone can see that repository and read from that repository. As my website’s repository is public, reading wasn’t a problem. However, pushing the code back to my repository would be writing, and that was a problem. Each GitHub project has a list of who can write to it and the creator of the project is on that list by default. But to write to the project, I needed my local Git tool to login to GitHub when needed and authenticate itself. To do this securely, I was going to have to dive into credentials.
GitHub Authentication: SSH vs HTTPS¶
Any time you log in to a website or to a program to gain specific privileges, you establish your credentials by supplying your user id and password. You tell the website or program “I can prove I am me, let me see my stuff!”. The GitHub website is no different that any of those sites. If you want to be able to see any of your private stuff or write to your stuff, it needs to verify who you are.
Going to the Authenticating with GitHub from Git, there are two choices that allow us to connect to GitHub: HTTPS and SSH. Both of these are valid options, allowing for enhanced security when Git connects to GitHub. Each of these options has different things going for and against it. After doing some research, it seemed to me to break down to the following:
|set up keys||set up credential manager|
|setup is more involved||easy setup|
|more secure||less likely blocked by firewall|
Looking at this information, I decided to go with SSH as I wanted to opt for more security.
SSH Access to GitHub¶
During my research at the GitHub site, I found this very good page on SSH over the HTTPS port. In it, they explain that there is a simple test to see if SSH will work from your system to GitHub. When you execute the following command:
ssh -T firstname.lastname@example.org
it will either return one of two responses. If it returns with:
> Hi *username*! You've successfully authenticated, but GitHub does not provide shell access.
then you can access GitHub via SSH without any issues. If you see the other response:
> ssh: connect to host github.com port 22: Connection timed out
then you have to setup SSH to connect to GitHub over the HTTPS port. This access can be verified with a small modification to the above command:
ssh -T -p 443 email@example.com
The command is now trying to establish a SSH session over port 443, and if you get the
You've successfully... response, it’s working fine. Running these tests myself, I found
that I got a timeout on the first command and a success on the second command. Following
the article, it recommends changes to
~/.ssh/config4 to include the following:
Host github.com Hostname ssh.github.com Port 443
The next time, when I executed the
ssh -T firstname.lastname@example.org command, the response was
You've successfully response. Now I was ready to set up the SSH keys.
Unique SSH Keys¶
Going back to the Authenticating with GitHub from Git, the next step was to generate a new SSH key pair and add it to the local SSH keyring. The page that points to generating a new key is pretty detailed, so I won’t try and improve over GitHub’s work. On my reading of the page, it seems to assume that if you will only have 1 key pair5 generated and that you will reuse that key pair for GitHub. I have issues with that practice, so I want to talk about it.
Having a bit of a security background from my day job, I want to limit exposure if something gets broken. Just from a quick search, there are articles by Leo Notenboom, Malware Bytes Labs, and WikiHow that all describe how you should have different passwords for each account, and in many cases, use a password manager. And to be honest, that was just the first 3 that I clicked on. There were a lot more.
I can sum up and paraphrase the justification raised in each of those articles by posing a single question: If someone breaks your password on one site, what is your exposure? If you have one password for all sites, then whoever breaks your password has access to that one site. If you have a different password for each site, the damage is limited to one site, instead of all sites using that password.
In my mind, using a key pair for credentials is a similar concept to using a user-id and password for credentials. Therefore, it followed that if I follow good security practices for passwords, I should also follow the same practices for key pairs as credentials.
Generating a New Key For GitHub¶
To ensure I have secure access to GitHub, I followed the instructions
for generating a new key.
To generate a distinct key pair for GitHub, I made one small modification to the instructions:
I saved the new key pair information with the filename
github-key instead of the default
id_ras. This resulted in the files
being created as the key pair. With those files created, I followed the remaining
instructions for setting up ssh-agent and uploading the key information to GitHub, replacing
any occurrence of
With that accomplished, I had a specific key pair specifically for GitHub and it was
I also had setup GitHub with the public portion of the credentials using the contents of
~/.ssh/github-key.pub, as instructed. The only remaining step was ensure that any SSH
connections to GitHub would use the GitHub credentials. Doing a bit more research on the SSH
configuration files, I quickly found that there was built in support for this by adding the
following to my
Host github.com User git PreferredAuthentications publickey IdentityFile /c/Users/jackd/.ssh/github-key
The location of
~/ on my Windows machine is
c:\Users\jackd\. The format for the
IdentityFile property is a standard Unix path format. This requires a translation from the Windows path format
C:\Users\jackd\.ssh\github-key to the Unix path format of
Combined with the change from earlier in this article, my
~/.ssh/config file now looked like:
Host github.com Hostname ssh.github.com Port 443 User git PreferredAuthentications publickey IdentityFile /c/Users/jackd/.ssh/github-key
Testing Against GitHub: GitHub Pages¶
Having performed a number of thorough tests of the above steps, everything passed without any issues! Now it was time to try and push some commits for the blog to GitHub.
To create a directory for the GitHub project, I largely followed these instructions detailed in the companion article on setting up your own static website. I then followed these instructions, adding the remote repository to my local configuration with the following line:
git remote add origin jackdewinter/jackdewinter.github.io
Having associated the directory with the remote repository, the final test was to make a
change to the directory, commit it, and push it to the remote. For this test, I used a
<html> <body> Hello world! </body> </html>
Adding the file to the directory, I staged the file and committed it with:
git add index.html git commit -m "new files"
and then pushed it to the remote repository with:
ssh-agent git push origin master --force
Crossing my fingers, I waited until I got a response similar to:
Counting objects: XXX, done. Delta compression using up to 8 threads. Compressing objects: 100% (XX/XX), done. Writing objects: 100% (XX/XX), XXX.XX KiB | 0 bytes/s, done. Total XX (delta XX), reused XX (delta XX) remote: Resolving deltas: 100% (XX/XX), completed with XX local objects. To blog:jackdewinter/jackdewinter.github.io.git XXXXXX..XXXXXX master -> master
With no error messages, I double checked the repository at
https://github.com/jackdewinter/jackdewinter.github.io and was able to see the
file present in the repository. Following through with the instructions for GitHub Pages, I
then went to
https://jackdewinter.github.io and was able to see the text “Hello world!” on
in the browser.
What Was Accomplished¶
This article started with my creation of a GitHub repository to contain
the files for my personal website using GitHub Pages. To securely access the repository, I
chose the SSH protocol and discovered that I needed to employ SSH over HTTP. For enhanced
security, I described a solid reason for wanting a unique SSH key for GitHub. Following that
advice, I generated a new key and then changed the
~/.ssh/config file to use SSH over HTTPS
and to point to that newly generated keypair. Finally, I committed a sample file to the
project and was able to see it pushed successfully to the remote repository, and displayed as
my personal home page.
My primary system is a Windows 10 machine, so instead of modifying the
~/.ssh/configfile, I modified the
%HOMEDRIVE%%HOMEPATH%\.ssh\configfile. On my system, that file is the
When a SSH key is generated, it comes in two parts. The private part is kept on the user’s system while the public part can be distributed to any interested parties. Together they are referred to as a key pair. ↩
So what do you think? Did I miss something? Is any part unclear? Leave your comments below.