TECH NOTES FOR NEWBIES
Instructions by the numbers
Github is amazing when you know how to use it. But when you don’t, it’s the bane of your existence. Couple that with little to no instructions on how to set up your Chromebook to work with Github, and you either:
- Want to toss your laptop through the window the way Uncle Phil throws Jazzy Jeff out of the mansion
- Stay up until 3:30 AM, determined to defeat Git (and lose), or
- A little bit of both.
Disclaimer: Please do not toss your laptop out of the window. The fact is, a lot of people have asked about this online because it’s a common frustration. You are not alone, and you’ve got this!
OK. Let’s assume you’ve already done the following:
- Added Linux & VS Code onto your laptop. If you haven’t done this yet, start here.
- Created a Github account.
- Created a repository on your Github account.
A few things to clarify before getting started:
Local: This term refers to your local drive and server. Think your computer, where you are currently typing and storing files.
Remote: This term refers to the server from which you’d like to push and pull files. In this case, the remote server is Github.
SSH: This is short for Secure Shell. SSH is an encryption tool that allows you to log into your remote server safely. You can get into the weeds here.
XYZ Project: This represents the folder that contains all of the contents you will need to push to your remote server. It is also the name of your repository in this scenario. Whenever this appears in the steps below, use the name of your folder and repository.
This isn’t as scary as it looks.
Sounds complicated though. Why not use HTTPS?
I had the same thought. I was already using HTTPS, but Github busted my groove. I was in the middle of creating a branch and wanted to push the file onto my remote server but was stopped by Github! As of November 2021, Github requires users to communicate with the remote server using SSH keys for login from the local terminal. I, therefore, had no choice but to figure this out.
Using Chromebook and SSH keys for Github took some investigating, trial and error, and significant sleep loss. So to ensure you won’t stay up until 3 AM figuring this out, here are clear step-by-step directions on how to retrieve your SSH key, set it up, copy it to Github, and get back to coding.
STEP ONE: Make sure you’re in the right place on your computer.
- Open your terminal.
- Ask your terminal where you are by typing this: pwd
- You want to get to the folder where you’ve cloned your repository because that is where you are communicating with Github. For example: if the terminal says you’re at /home/YOURNAME, but the files that will be pushed or pulled are in the “XYZ-Project” folder, get to the XYZ-Project folder before going to the next step.
Remember, you can get to your folders by using the command for cd. Use cd to get to the XYZ-Project folder in the same way you would if you were using your mouse and going further into subfolders. Example:
In the command line, type: cd ‘XYZ-Project’. If the terminal says no or says the file doesn’t exist, and you know it does, ensure you’ve spelled the name of the folder correctly. If that isn’t the issue, it’s because your file is buried in subfolders. Remember: you’re typing what you’d typically use your cursor to do. If you’d normally have to go to Documents, then a folder called Projects 2021, then XYZ-Project using a cursor, you’d type that out here in the command line.
Here’s how that looks: cd ‘Documents’ (hit enter), then cd ‘Projects 2021’ (hit enter). Finally, type cd ‘XYZ-Project’ (hit enter). Sometimes I can’t remember which folder something is in, so don’t forget to use ls to see which subfolders exist in a big folder.
Now that you’re in the right place, we can communicate with the remote server. The assumption, at this point, is that you’ve at least cloned the XYZ-Project folder from your Github repository.
STEP TWO: Create an SSH Key on your local server.
- Check to make sure you don’t already have SSH keys here. In the command line, type ls -al ~/.ssh
- If nothing appears, you’re good to go. If something appears and a line ends in id_rsa, then this means you have a key already, and you can choose to overwrite it or use this key.
- Now you can generate your key. Do this by typing in the command line: ssh-keygen -t rsa -b 4096 -C “[email protected]” (Type the email address used to sign up for your Github account).
- If that doesn’t work, type in the command line: ssh-keygen -t rsa
- The command will then request a file to save the key. Just hit enter. You will then need to enter a passphrase, which will be for your SSH key. Careful here; you cannot see the phrase as you’re typing it. Hit enter. Remember this passphrase — you will need it for step 7.
- Now you need to link your local computer to the ssh-agent. Do this by typing the following into the command line: eval “$(ssh-agent -s)”.
- If you see a line that says: Agent pid #### (where # will show up as numbers in the terminal), you’re good to go. Move to the next step.
- Type the following command: ssh-add -K ~/.ssh/id_rsa
- Remember that passphrase you entered on step 4? The command line should now prompt you to enter it here. If you forgot the passphrase, you could generate a new key by going back to step 3. At some point, the terminal may ask if you want to write over the previous key you created. Just say yes.
STEP THREE: You’re Unable to copy the SSH key based on the previous step. Do this:
- The commands clip < ~/.ssh/id_rsa.pub and pbcopy < ~/.ssh/id_rsa.pub ARE NOT GOING TO WORK.
- In the command line, type cat ~/.ssh/id_rsa.pub
- Your key appears! It will be long and full of letters, numbers, and intermittent “+” signs. The prefix of this long key is going to be: ssh-rsa. You will also see your email address at the end of the key. The email address is also part of the key. Beginning with the prefix, highlight and copy the entire key by highlighting it with your cursor. Hint: when you release the cursor, a small notification will flash onto the screen saying “Copied.”
STEP FOUR: Add your SSH key to the remote server (Github).
- Go to your Github settings. A list of account settings will appear to the left of the page.
- Under account settings, select “SSH and GPG Keys.”
- Select the button that says “New SSH Key.”
- In the title, label the key. It’s recommended you name it after your local hardware. So in this instance, it would be “Chromebook.”
- Paste the key you copied from your terminal into the space that says “Key.”
- Select Add SSH Key to save.
YOU DID IT.
But there is one more thing you need to do: change the protocol so that your terminal doesn’t prompt you to use the password but instead uses your SSH key.
- Go back to your terminal. You should still be in your project folder. You can check by asking your terminal where you are (the command is pwd). If you’re not in your project, use the change directory command (cd) to get there.
- Next, remove the “HTTPS” setting from your folder. In the command line, type git remote rm origin. It’s going to look as if nothing happened. This is good.
- Next, go to your repository in GitHub. Select the repository that correlates to your project. Then select the code button for your repository. This is where you found your HTTPS link initially. This time, you’re going to use the SSH link instead. Copy the SSH link.
- Go back to your terminal and type git remote add origin, and next to it, paste the link you just copied from your repository. It should look like this: git remote add origin [email protected]:YOURGITUSERNAME/NAMEOFREPOSITORY.git.
- For clarification: paste the link directly next to the command git remote add origin. Only after you add the link should you select enter. After this, it should look like nothing happened.
- But it did. To check, type git remote -v
- Two links will show up. But you will not see HTTPS in the links, and that’s how you know it worked!
From this point, you’re good to go, and your repository is now set up with this SSH code.