Push a Local Project to GitHub First Upload with Git and SSH

To push a local project to GitHub for the first time using SSH, you need to set up an SSH key, create a repository on GitHub, connect your local folder to it, and run a few git commands. This guide walks through the entire process step by step, from generating your SSH key to verifying the upload, and covers common pitfalls like authentication errors and the “remote origin already exists” message.

Why Use SSH Instead of HTTPS?

GitHub lets you interact with repositories over HTTPS or SSH. With HTTPS, you authenticate using a personal access token (passwords are no longer accepted for git operations). With SSH, you authenticate using a public/private key pair: your computer holds the private key, and GitHub holds the public key. Once set up, you never need to enter credentials again, and the connection is encrypted. SSH is especially convenient for frequent pushes and for users who prefer not to manage tokens. The main trade-off is the initial setup: you must generate a key, add it to your SSH agent, and register it with GitHub.

Prerequisites

Git installed on your local machine (check with git --version).
A GitHub account with a verified email.
SSH client (usually preinstalled on macOS and Linux; on Windows, Git Bash includes one).
A local project folder that you want to upload.

Step 1: Generate an SSH Key Pair

Open your terminal (Git Bash on Windows, Terminal on macOS/Linux) and run:

ssh-keygen -t ed25519 -C "your_email@example.com"

Replace the email with the one associated with your GitHub account. You will be asked where to save the key; press Enter to accept the default location (~/.ssh/id_ed25519). Next, you can set a passphrase for extra security (optional, but recommended). This creates two files: id_ed25519 (private key) and id_ed25519.pub (public key).

Step 2: Add the Key to the SSH Agent

Start the SSH agent in the background and add your key:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

If you set a passphrase, you will be prompted to enter it. On Windows, you might need to use the ssh-agent service; Git Bash usually handles this automatically.

Step 3: Add the Public Key to GitHub

Copy your public key to the clipboard:

cat ~/.ssh/id_ed25519.pub

Then, in your browser, go to GitHub → Settings → SSH and GPG keys → New SSH key. Give it a descriptive title (e.g., “My Laptop”), paste the key, and click Add SSH key. You may be asked to confirm your GitHub password.

Step 4: Create a New Repository on GitHub

Click the “+” icon in the top-right corner of GitHub and select “New repository.” Choose a name (e.g., my-project), optionally add a description, and decide whether it should be public or private. Do not initialize the repository with a README, .gitignore, or license, because you already have a local project and adding those files will cause conflicts on the first push. Click “Create repository.”

Step 5: Initialize Git Locally and Connect

Navigate to your project folder in the terminal:

cd /path/to/your/project

If your project is not already a Git repository, initialize one:

git init

Add your files to the staging area and make the first commit:

git add .
git commit -m "Initial commit"

Now link your local repository to the GitHub remote using the SSH URL. On the GitHub repository page, click the green “Code” button and select the SSH tab; copy the URL (it looks like git@github.com:username/repo.git). Then run:

git remote add origin git@github.com:username/repo.git

If you get a warning that the remote already exists, check with git remote -v and either update it (git remote set-url origin ...) or remove it first (git remote remove origin).

Step 6: Push to GitHub

Finally, push your local branch to the remote. The default branch is usually main (or master on older setups). To push and set the upstream tracking:

git push -u origin main

If your branch is named master, replace main accordingly. The -u flag sets the upstream so future pushes can be done with just git push. You may see a prompt asking to confirm the host key; type yes and press Enter. After a few seconds, you should see a message like “To github.com:username/repo.git” and a summary of the pushed objects.

Verifying the Upload

Refresh your GitHub repository page. You should see your files listed. You can also run git status locally to confirm everything is up to date. To test the SSH connection, run:

ssh -T git@github.com

You should see a message like “Hi username! You’ve successfully authenticated, but GitHub does not provide shell access.” This confirms your SSH key works.

Common Problems and Fixes

Permission denied (publickey): Your SSH key is not registered with GitHub, or the agent isn’t running. Re-check steps 2 and 3, and ensure you copied the entire public key.
Host key verification failed: When connecting for the first time, you must accept the host key by typing yes. If you previously declined, you can remove the old host from ~/.ssh/known_hosts and try again.
Remote origin already exists: This happens if you already added a remote (perhaps via HTTPS). Use git remote set-url origin git@github.com:username/repo.git to switch to SSH.
Failed to push some refs: This usually means the remote has commits you don’t have locally (e.g., you initialized the GitHub repo with a README). Pull first with git pull origin main --rebase, then push again.
Wrong branch name: If your local branch is master, use git push -u origin master. You can rename it with git branch -m main.

Frequently Asked Questions

Do I need to generate a new SSH key for each computer?

Yes, each computer should have its own SSH key pair. You add the public key from each device to your GitHub account. If you lose a device, you can delete its key from GitHub to revoke access.

What if I already have an SSH key?

You can reuse an existing key. Check for ~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub. If you use a different key name, specify it with ssh-add ~/.ssh/your_key and ensure GitHub has the matching public key.

Can I push an existing repository that was created with HTTPS?

Yes. Change the remote URL to the SSH version with git remote set-url origin git@github.com:username/repo.git. No need to reinitialize the repository.

What is the difference between `git push` and `git push -u origin main`?

The -u flag (or --set-upstream) sets the local branch to track the remote branch. After that, you can simply type git push without specifying the remote and branch. It is recommended for the first push.

How do I push a project that has subdirectories or large files?

Git handles subdirectories automatically. For large files (over 100 MB), you should use Git LFS (Large File Storage), but that requires separate setup. For normal projects, just git add . includes all files except those listed in .gitignore.

Is SSH faster than HTTPS?

In practice, the speed difference is negligible for typical use. The main advantage of SSH is convenience: no need to enter credentials each time. HTTPS with a credential helper can also be convenient, but SSH is often preferred for security and automation.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →