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.

Using GitHub is a prerequisite of most tutorials on the CircleCI blog, so it is helpful to learn to use it. In this tutorial, I’ll show you how to push a project to GitHub.

Prerequisites

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, we can start the tutorial.

Setting up

To keep things simple, we’ll use a single HTML file. You can review the HTML file 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:
wget https://raw.githubusercontent.com/CIRCLECI-GWP/profile/main/index.html

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

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

Initializing Git

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

Run:

git init

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

Adding files

With Git initialized, we 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.

Run:

add index.html

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

Committing files

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

Run:

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 github.com 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 https://github.com/NdagiStanley/new-repository.git
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.

Conclusion

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 setting up a CircleCI project based on your GitHub repository. 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.


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