How to upload a new project to GitHub with Linux and SSH, no password

Introduction

This article is a step-by-step guide to help beginners set up Git for a new project and synchronize it with GitHub. Additionally, you will learn how to use SSH keys to avoid repeatedly entering passwords. At the end, we will also cover how to create tags and publish releases for your project.

Prerequisites

Create a GitHub Account and Set Up a New Repository

Before we begin, you will need a GitHub account and a repository to store your project. This process is intuitive and includes direct assistance from GitHub during the steps. Make sure to follow the prompts on the platform to complete this initial setup.

Development Environment

The commands presented in this article were tested on Linux Slackware 15.0, using the native tools Git (version 2.46.3) and OpenSSH (version 9.9p2). The commands are generic and should work on any Linux distribution with Git and SSH installed.

Initializing Git in the Local Project

Step 1: Configuring Git to Use main as the Default Branch

Many modern platforms (such as GitHub, GitLab, and Bitbucket) adopt the name main as the default branch. To ensure new repositories automatically use main as the primary branch, adjust Git's global configuration by running the following command:

$ bash

git config --global init.defaultBranch main

With this configuration, the git init command will automatically create the main branch, eliminating the need to rename it manually.

Recommended reading: Learning the basics of Git and the use of branches.

Step 2: Initializing the Repository

For a project named telazul, the following steps are necessary to set up Git in this directory and prepare the project for synchronization with GitHub.

$ bash

# Navigate to the project directory  
cd telazul/  

# Initialize the Git repository  
git init  

The git init command is used only once to create the necessary structure for the repository. To check the current branch name and rename it if necessary, use the following commands:

$ bash

# Check the current branch name  
git branch  

# Rename the master branch to main  
git branch -m master main  

Step 3: Adding Files to the Local Repository

Add all files and directories to the repository and save the changes with an informative message:

$ bash

# Add all files in the current directory recursively  
git add .  

# Permanently save the changes with a descriptive message  
git commit -m "Initial commit: adding project files"  

The git add . command adds all modified or new files to the index, while git commit creates a snapshot of the current state of the files, saving the changes permanently. Since you can recover the exact state of this commit in the future, the associated message should be clear and descriptive to facilitate identifying the changes made.

The steps above configure Git in the local project. They are independent of GitHub integration and can be used in any Git workflow.

Configuring SSH Access to GitHub

The project will be transferred using SSH, a secure and practical protocol for transferring files over the internet. For this, you need to configure SSH keys, which will act as credentials, allowing login to GitHub without the need to enter a password.

$ bash

# Generate keys using the ed25519 algorithm  
ssh-keygen -t ed25519

When prompted, press Enter ↲ to keep the default location ~/.ssh/ and to use a blank password. If you already have SSH keys compatible with GitHub (such as id_rsa or id_ed25519), there is no need to create new ones.

Recommended reading: What SSH keys are and how to use them instead of your network password.

Adding the Public Key to GitHub

To transfer the public key between Linux computers, you can use the ssh-copy-id command. However, on GitHub, you must manually copy and paste the key into the platform's graphical interface.

The public key is stored in the file ending with .pub. To display its content, use the following command (replace your-username with your system username):

$ bash

cat /home/your-username/.ssh/id_ed25519.pub  

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEDbDtQNhBvGd292FgKDRgqhiXGiLHo32ZYXCSS017d5 your-username@host-name  

Copy the entire line starting with ssh-ed25519 (public key) and:

1. Access GitHub and click on the menu with your avatar in the top-right corner.
2. Navigate to Settings > SSH and GPG Keys.
   • You can also use the direct link: https://github.com/settings/keys.
3. Click on New SSH Key,
4. Fill in the Title field with a descriptive name for the key (e.g., "My Notebook's SSH Key").
5. Paste the public key into the Key field.
6. Click Add SSH Key to save.

After configuration, the key will appear listed on the SSH keys page, as illustrated below:

Uploading the Project to GitHub

To connect the local repository to the remote repository on GitHub, use the following command. It adds the alias origin to the remote repository, making it easy to reference in future operations.

$ bash

git remote add origin git@github.com:your-username/your-repository.git  

Make sure to run the above command inside the project folder and replace your-username with your GitHub username and your-repository with the name of the repository created on the platform.

Now, upload the project to the remote repository with the following command:

Warning! The -f parameter will delete all existing files in the remote repository. Use it only when necessary, such as when the GitHub repository is newly created.

$ bash

git push -u -f origin main

• The -u (or --set-upstream) parameter sets origin as the default reference for the main branch. After this configuration, you can use the git push and git pull commands without specifying the remote repository or branch.
• The -f (or --force) parameter forces the update of the remote repository, overwriting any existing content. This parameter is useful when starting a new project if the remote repository contains default files (such as LICENSE or README.md) that prevent the initial push.

Synchronizing Changes from the Remote Repository

Go to the GitHub website and create the README file with some content. To synchronize these changes from the remote repository to the local repository, run the following command from the project folder:

$ bash

git pull

The git pull command fetches the latest commits from the remote branch and applies them to the local branch.

As mentioned earlier, when uploading the project with the git push command using the -u parameter, the GitHub repository is set as the default reference. This eliminates the need to specify the remote repository name (origin) in subsequent commands.

After running the command, verify that the README file created remotely is now present in the local project folder.

Updating Files Locally

Edit the README file in the local repository by adding a new line. Then, record the changes and send them to the remote repository with the following commands:

$ bash

git commit -a -m "Update README file"  

git push

The -a parameter automatically stages all modified or deleted files in the local repository. However, it does not include new files (files not yet tracked by Git). To include new files, use the git add command.

The -m parameter allows you to add a descriptive message to the commit.

The git push command updates the remote repository on GitHub with the recent changes made to the local project folder.

Recommended reading: Using Git to share and collaborate on a project.

Semantic Versioning

Before diving into tags and releases, it is important to briefly understand the numbering used in software versions. Semantic Versioning (or SemVer) is a widely adopted convention for naming software versions, facilitating communication about changes and ensuring compatibility.

It follows the format:

MAJOR.MINOR.PATCH

• MAJOR: Incremented when there are backward-incompatible changes (e.g., changes that break APIs or functionality).
• MINOR: Incremented when backward-compatible features are added (without breaking current functionality).
• PATCH: Incremented for bug fixes or minor improvements that do not alter existing functionality.

Examples

• 1.0.0: First stable version of the software.
• 1.1.0: Addition of new features without breaking compatibility.
• 1.1.1: Bug fixes for version 1.1.0.
• 2.0.0: Changes incompatible with version 1.x.x.

It is a recommended practice for projects that need to clearly communicate the state of development and changes introduced in each version.

Naming Versions with Tags

A tag is a static reference pointing to a specific commit in Git history. Unlike branches, which can advance and change over time, tags are fixed and do not change once created. This makes them ideal for marking important events, such as releasing versions that can be made available for users to download.

$ bash

git tag v1.0.0

This command creates a tag named v1.0.0, generating a definitive version of the project containing all files and directories in the state they were in at the time of the last executed commit.

The prefix v (for "version") is a convention adopted to identify version tags, making them easier to distinguish in Git history, especially among other markings (e.g., beta-test).

To name a specific commit, different from the current one, with a tag, use:

$ bash

git tag tag-name commit-hash

To discover the commit-hash, refer to this topic.

The previous commands create lightweight tags. Another option is annotated tags, which are more detailed and include metadata such as a message, author, and date. They are recommended for marking important versions.

To create an annotated tag, use the -a parameter:

$ bash

git tag -a v1.0 -m "Stable Version 1.0"

Other useful commands for managing tags:

$ bash

# List all tags  
git tag  

# List all tags and their commits  
git log --oneline --decorate  

# View details about a specific tag  
git show tag-name  

Pushing Tags to the Remote Repository

By default, tags are not automatically pushed to the remote repository when using the git push command. To push tags to the remote repository, use the following commands:

$ bash

# Push a specific tag  
git push origin tag-name  

# Push all tags at once  
git push origin --tags  

Practical Example

Suppose you have just completed version 1.0 of your project. You can mark this moment with an annotated tag and push it to the remote repository by following these steps:

$ bash

# Create the tag locally  
git tag -a v1.0 -m "Stable Version 1.0"  

# Push the tag to the remote repository  
git push origin v1.0  

Deleting Tags

Tags in Git are immutable references by design, meaning once created, they always point to the commit they were assigned to. However, they can be deleted.

To delete a local tag:

$ bash

git tag -d tag-name

To delete a remote tag:

$ bash

git push origin --delete tag-name

This command will remove the tag on GitHub.

Updating Tags

Tags in Git cannot be updated directly. However, you can simulate an update by deleting the existing tag and creating a new one with the same name. Follow the steps below:

$ bash

# Delete the local tag  
git tag -d tag-name  

# Delete the remote tag  
git push origin --delete tag-name  

# Create the new tag with the same name  
git tag -a tag-name -m "New tag message"  

# Push the new tag to the remote repository  
git push origin tag-name  

Attention! Best Practices When "Updating" Tags

Although it is technically possible to delete and recreate tags with the same name, this practice can cause confusion, especially if the original tag is already being used by others. Changing a tag after it has been shared can lead to inconsistencies in the project's history.

Avoid altering published tags: If the tag has already been shared with other developers or used in official releases, prefer creating a new tag with a different name (e.g., v1.0.1 instead of reusing v1.0).

Creating a New Release on GitHub

Start by creating a local tag to indicate your project's version and push it to the remote repository on GitHub:

$ bash

# Create the tag locally  
git tag -a v1.0.0 -m "Stable Version 1.0.0"  

# Push the tag to the remote repository  
git push origin v1.0.0  

On GitHub:

1. Go to the releases page.
   • https://github.com/your-username/your-repository/releases
2. Click on Create a new release.
3. Fill in the release details:
   
   • Choose a tag: Select the tag you created (e.g., v1.0.0) or create a new one directly on this screen. In this example, the tag is created locally and pushed to the remote repository, but the reverse process is also valid.
   • Release Title: Provide a descriptive title for the release (e.g., "v1.0.0 - Stable Version").
   • Describe this release: Add a detailed description of the release. Include information such as what was added, fixed, or changed, links to documentation, related resources, etc.
   • Set as a pre-release: Check this option if the version is beta or experimental. Otherwise, leave it unchecked.
4. Publish by clicking Publish release.

After publishing the release, GitHub automatically makes the files associated with the tagged commit available. You can download them as a .zip or .tar.gz file.

Conclusion

This article was written as a practical guide for people to consult the necessary steps to create their first projects and make them available for download on GitHub. If you managed to set up your repository, create tags, releases, and share your work with the world, it has served its purpose.

Continue exploring Git and GitHub, and take advantage of all the possibilities these tools offer to organize, share, and collaborate on your projects.

References

• https://docs.github.com/en/get-started/start-your-journey/uploading-a-project-to-github
• https://stackoverflow.com/questions/12799719/how-to-upload-a-project-to-github
• https://www.digitalocean.com/community/tutorials/how-to-push-an-existing-project-to-github

Site Notes

This is not my original language and I don't speak it very well. I used my little knowledge and translators tools to compose the text of this article. Sorry for possible spelling or grammatical errors, suggestions for corrections are appreciated and can be sent to the contact email in the footer of the site. My intention is to share some knowledge and I hope this translation is good enough.

Some of the content on this website, including text, images, graphics and other materials, may be generated or enhanced by artificial intelligence (AI) tools. For more details on the use of AI, please see our Term of Use.