GitHub is a web-based platform used for project version control and codebase hosting. GitHub uses Git, a widely-used version control system. GitLab and Bitbucket are similar tools.

GitHub is one of the most popular version control platforms and is used widely across the software industry, so it is helpful to learn to use it. In this tutorial, I’ll show you how to push a project to GitHub.

If you are a GitLab user, you can also check out our tutorial on Pushing a project to GitLab.


To follow this tutorial, a few things are required:

  1. Basic knowledge of Git
  2. Git installed on your system
  3. A GitHub account

With these items in place, you can start the tutorial.

Setting up

To keep things simple, this tutorial uses a single HTML file. You can review it here.

There are a few ways to get the HTML file:

  • Copy the code in the gist (linked above) into an index.html file
  • Go to this link, then click Download this one-page web-profile.
  • Use the Terminal (or equivalent like Command Prompt or PowerShell). Go to the project folder you want to use and run:

Using any of these methods will result in an index.html at the root of your directory.

For the rest of the tutorial, you will use the Terminal to run commands. Unless instructed otherwise, run commands at the root level of your project directory.

Initializing Git

Because you created our file locally, you need to push it to GitHub to store it there. The first step is initializing Git.


git init

The git init command turns your directory into a new Git repository.

Adding files

With Git initialized, you need to mark the HTML file so that it is included in the next commit. This process is also called “staging”.

Note: A commit is a snapshot of the history of changes to a file.


git add index.html

This command marks the index.html file so it can be included in the next commit.

Committing files

Your file is now marked and ready for its first commit.


git commit -m "add index.html"

The text following -m is the commit message. It is a human-friendly reminder about what changes are in the commit.

Pushing to GitHub

Pushing uploads all your local commits to the remote repository. This makes the changes in your file available to people you are working with. There are two parts to this process:

  1. Creating a repository
  2. Pushing the project

Creating a GitHub repository

In your browser, go to <> and log in if you haven’t yet. Click the plus sign icon at the top right of the page. Then select New Repository.

New repo

Select Owner, enter Repository name, then click Create repository. I have used the name new-repository for this tutorial. You will be using this name later on, so make a note of it.

Create repository

There you have it, a sparkling new repository. If this is your first one, congratulations! You have reached a programming milestone.

Stay on this page to complete the next step.

Pushing the project to GitHub

Remember, you already have a local repository with one file, and you have committed the changes you made to it. The next step is to push these changes to the newly created GitHub repository.

Push existing repo

Paste these commands in your Terminal and press Enter to execute them:

git remote add origin
git branch -M main
git push -u origin main

Note: Replace the username shown in the example with your GitHub username..

After running these commands, reload the browser page. Your index.html file is now listed in the online repository.

You can make more updates to the repository by running these commands in order:

git add .
git commit -m "Commit message"
git push origin main

Replace the sample text, Commit message, with a descriptive one of your own. If you are working on a branch other than main, use the name of your branch. You can read more about git branching here.


In this tutorial, you pushed a local Git repository to GitHub. Getting comfortable with Git and GitHub will let you move on to the next step of the development workflow: adding software testing and automating your tests with continuous integration. Read Setting up continuous integration with CircleCI and GitHub to get started.

GitHub and other Git-based version control systems are widely used in software development and other disciplines that need version control. Understanding them is a key addition to your developer’s toolkit. If you are still deciding which version control platform is right for you, be sure to read GitLab vs. GitHub: Choosing the right version control service.

Stanley is a Software Engineer and Technical Copywriter who has worn several hats, including technical team leadership and community engagement. He describes himself as a digerati (literate in the digital space).

Read more posts by Stanley Ndagi