This guide is for folks who are new to using GitHub and git, and also perhaps new to terminal usage (bash or zsh) in general.
This guide is up-to-date with changes made to GitHub authentication in 2021 and 2022.
Most Common Troubleshooting: Are you dealing with the
remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead.error? See the section Creating an "personal access token" to use as a password at the bottom of this tutorial.
Prerequisites
Prerequisite skills: You should be able to open a terminal running Bash (Linux, Windows, old macOS) or Zsh (recent macOS), and be familiar with basic commands, such as ls and cd. You should be familiar with editing code files using a text editor, such as writing HTML files using VS Code. You should be familiar with at least the terminology of basic git concepts: repository or "repo" for short (a directory that you are using git to track changes with and may be shared with other git users), a "commit" (a "savepoint") and so on.
Prerequisite computer setup & accounts: 1) Sign-up for a GitHub account and log-in, if you haven't already, and 2) install & configure Git for your platform (Ubuntu Linux, use sudo apt install git, macOS, install brew and then run brew install git, and for Windows, install "git-bash")
Creating a new repo on GitHub
Step 1: Go to the plus & select new repo
In this tutorial, we'll start by making the repo first on GitHub, since this typically requires the fewest steps.
Click on the plus in the upper-right corner of the screen, and select new "repo" to be taken to the new repo screen.
Step 2: Fill in details
Type in a name and details for your repository, and make it public.
Step 3: Check "create with README.md" & create
We'll start with a README.md file, to make it easier to confirm the repository was made when we clone it locally, and so that GitHub fully sets-up the repo on their end.
Cloning GitHub repo to local
Step 1: Copy the URL
Click the green "CODE" button and copy the URL
Step 2: Paste URL in a git clone command
Open up a new terminal, and find a good location for your code. Type in "git clone" followed by a space, and then paste in the URL.
Step 3: Change into new directory and confirm success
Git will create a new directory with the name of your repo. In the GIF demo below, which covers all 3 steps above, that will be testingrepo. In that case, we'll want to do a cd testingrepo/ (or whatever you called your repo), and then do a ls to confirm the README.md that GitHub generated is indeed copied locally. Finally, we'll want to do a git status to ensure it is connected to GitHub as expected.
(Steps 1, 2 and 3 below:)
Making changes and pushing up
Step 1: Making a change
It's up to you how you want to add files or make changes. You can use an editor (e.g. VS Code) to create a new file in that directory, such as an "index.html" file. You could also delete / move / rename / copy files within your graphical file-browser.
Tip: You can use git status to verify that you succesfully made a change. Note how in this example it shows it as an "untracked" file. This means you haven't told git that this change was deliberate and one that you want to track. That's the next step.
- Troubleshooting Step 1: Make sure you are in the same directory, both with the change you make and when you run the command.
Step 2: Add & commit the change
Once you've made a change, it's time to add it to the "staging area" of the repo with git add -A, and then commit it, with git commit -m "any notes". Note the value of git status before and after each of these commands. The git status command gives you a clue of what status your repo is in, and what you need to do next.
- Troubleshooting Step 2: Make sure you use the
-m "message"part of the commit command. If you do not, it will likely put you into a difficult text editor (eithernano, for Linux, orvifor macOS). Whilenanois somewhat usable (read the help at the bottom, the^symbl means the Ctrl key, e.g. the^Xhelp at the bottom means Ctrl+X exits), the macOS defaultviis very hard for beginners (e.g. Escape followed by:q!followed by Enter to exit). Unless you like hard editors like these, then just use the-margument to avoid it!
Step 3: Push the change up
Now that you have a "commit" locally (that is, the current contents of your files have been saved into the .git/ directory), you will need to push upward. This can be done with the git push command.
- Troubleshooting Step 3: Did it just ask for a password? Use a personal access token instead. Look at "Creating an auth token to use as a password" below to know what to do next.
(Steps 1, 2 and 3 below:)
Optional: Making another change and pushing up
Now, if you want to share any changes or additions you make on GitHub, you'll want to repeat Steps 1-3: Make a change, then run git add -A and git commit -m "message goes here", followed by git push
Creating an "personal access token" to use as a password
Without an SSH key set-up, it will show something like this instead:
$ git push
Username for 'https://github.com': michaelpb
Password for 'https://[email protected]':
remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead.
remote: Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ for more information.
fatal: Authentication failed for 'https://github.com/michaelpb/testingrepo.git/'
In this situation, the quickest way to push is to generate a "personal access token" (basically, a randomly generated password) instead of the password that you used when you created your GitHub account.
Step 1: Getting to "Generate a new access token"
Click on your profile, then click on Settings, then click on Developer settings, then click on Personal access tokens then click on the button that says Generate an access token, then enter your password, and you will be at the access token generation form
Step 2: Fill in details, and paste in token
Finally, check the box next to repo to enable repo access, optionally set an expiration date and add a note to yourself (description), and then paste in the password. Note that there is no way to ever recover this password again if you do not save it, meaning you should delete old ones and generate a new one if you ever lose it!
Important: Make sure to check the "repo" box when creating a new auth token! Otherwise, you'll get a 403 error when you try to use it.
- For more information, follow the "Creating a personal access token" guide from GitHub
Consider saving a personal access token somewhere safe, such as a password manager. Or, you can always just generate a new one every time, although that can be tedious.
In the long run, you'll want to set-up SSH key based authentication. However, for beginning coding school students, generating a personal access token might be enough!
Michael Bethencourt
Michael is a software developer and instructor. His favorite teaching challenge is teaching big computer science concepts to total newbies. He believes that complex concepts don't need to be complicated! His favorite engineering approach is full stack thinking: recognizing complexity that can be shifted between low-level infrastructure and JavaScript, or vice-versa. When he's not coding, he's probably doing political work, playing video games that feel too much like work, and counting down the days until first contact.