Version control systems are the foundation on which modern development workflows are built. They reduce the complexity of collaboration while empowering developers to track and control the evolution of source code. Git is the most widely used open-source version control system, and that’s why cPanel & WHM makes it easy to host Git repositories and automatically deploy code from repositories to production.
In this article, we introduce Git and show you how to create and use remote Git repositories hosted on your cPanel server. We’ll also explain cPanel Git Version Control’s killer feature: automatic code deployment.
What is Git?
Git is a version control system created by Linus Torvalds, who is also the lead developer of the Linux kernel. Version control systems track changes in source code and help multiple developers to work efficiently on the same codebase. With Git, developers can manage their code, safely merge contributions from many sources, and revert code to an earlier version if something goes wrong.
A software project’s Git repository is often hosted on an external server. Individual developers download a copy to their laptop or desktop computer, make changes, and then upload their new version to the server. As you can imagine, coordinating changes from many different developers is enormously complicated. Git aims to make that process, if not simple, then at least manageable.
Here are a few key terms to help you understand how Git works before we get to setting up a repository and managing code.
- Repository: A directory managed by Git that contains a project’s code files and the information Git needs to provide version control features.
- Remote repository: A repository hosted on a remote server, often the “official” source of a project’s code. In contrast, a local repository is a developer’s version of the code.
- Commit: A commit is a snapshot of the code at a specific point in time. Committing is creating a commit, which adds a new snapshot of the code to the repository.
- Clone: A complete copy of a repository. Developers clone remote repositories when first creating a local repository to work on.
- Push: Developers push changes from their local repository to the remote repository.
- Pull: Developers pull changes from the remote repository to their local repository. Pulling makes sure that any changes in the remote are incorporated into the developer’s local version.
We’ve omitted some technical details from these definitions, but if you’d like to learn more, the Official Git Glossary is a valuable source of information.
Hosting Git Repositories with cPanel
Git is a flexible tool that can be used in many different ways, but we’ll focus on a simple workflow that hosts and manages a Git repository with cPanel. We’re not going to discuss branches in this article, but there will be some resources at the end if you want to broaden your understanding.
We’ll explain how to:
- Create a Git repository on your cPanel server.
- Clone the repository and pull code changes to a local development machine.
- Push code changes back to the server.
- Use cPanel’s Git Management interface to deploy a site into production.
After reading this article, you will be able to host your site’s code in a remote version control system while writing code on your local laptop or desktop computer.
Prerequisites
Before we begin, you’ll need:
- SSH access to your cPanel account.
- A cPanel account with the Git Version Control tool, which is available from cPanel Version 82.
- A local development machine with a terminal and an SSH client, such as Windows Terminal or Terminal.app on macOS.
- Git installed on your local machine. You can install Git by following the project’s installation instructions.
To push code to the server’s Git repository, you will also need to create an SSH key pair and install the public key on your server. We’ll show you how to do that first.
Create and Upload SSH Keys for Git
We’ll use SSH to communicate securely with our Git repositories and SSH keys, a convenient alternative to passwords, to authenticate with the server.
SSH keys come in pairs, a public key and a private key. The private key is kept on your local development machine. The public key is uploaded to the server. You can only authenticate with SSH on the server if you have the private key that matches the uploaded public key.
We’ll generate the key pair on our local development machine with OpenSSH and use cPanel’s SSH Access tool to upload the public key. OpenSSH should be installed already on macOS and Linux, and you can follow this documentation to install it on Microsoft Windows.
Open your terminal and run the following command:
ssh-keygenFollow the instructions to select a name for the key pair and a passphrase. If you choose to enter a passphrase, make sure you remember it. You won’t be able to use the keys without it.
Next, open the directory you created the key pair in, where you’ll find a couple of files. We’re interested in the one called id_rsa.pub. Open it in a text editor and copy the contents.
Navigate to the SSH Access page in cPanel, which is in the main page menu’s Security section.
Click Manage SSH Keys and then Import Key.
Choose a name for the key and paste the public key into the bottom text area. Then click Import.
Now we’re set-up with SSH keys, we’ll be able to clone, push, and pull code with Git. But first, we need a repository.
Create a New Git Repository on Your Server
The remote repository will be the canonical location of the site’s code during development. People who work on the code will download it from here and upload their changes, which Git will merge with the existing code.
Use the File Manager to create a new directory on your server to store the site’s development files. Do not use spaces in the directory’s name.
Open cPanel’s Git Version Control interface.
Click the Create button and enter the location of the project directory. You can also give the repository a name. Make sure the Clone a Repository switch is not activated. When you’re finished, click Create at the bottom of the page.
Clone the Repository to a Local Development Machine
To use the remote repository on our local dev machine, we must first clone it to create a local repository. Cloning creates a complete copy. Open a terminal on your local device and use cd to move to a directory you would like to store the project’s files in.
Then, run the following command, replacing the username, domain, and location with your remote repository and server details.
git clone ssh://user1@example.com/home/user1/NewSiteDevGit may warn you that you have cloned an empty repository. We’ll fix that in the next section, but before we do, let’s look at how we can sync changes in the remote repository to our local environment.
We don’t want to clone the server’s repository every time something changes. We’re only interested in the differences between the server’s copy and our local copy. To only get what’s changed, we use the pull command. Git commands are run from inside the project directory.
git pull originIn this command, “origin” means the remote repository, the one on our server. It’s a good idea to pull from the remote whenever you start a new development session so that you always have the most up-to-date version of the code.
Push Local Changes Back to Your Server
Let’s create a file on our local machine and push it up to the server. For demonstration, we’ll create a simple index.html file. Open your preferred text editor, paste the following HTML, and save it in the project directory.
<!DOCTYPE html>
<html>
<head>
<title>New Site</title>
</head>
<body>
<h1>New Site Placeholder Page</h1>
<p>We'll use Git to push this file to our remote repository.</p>
</body>
</html>First, we have to stage the new file, which tells Git that we want to include it in the repository.
git add index.htmlNext, we commit our changes.
git commitGit will ask you to enter a short description of your work with the default terminal text editor. Write a message, save the file, and close the editor. If your default editor is Vim or Vi, press “i” to enter insert mode, type your message, press escape, then type “:wq”, followed by the enter key.
Now all that’s left is to push our local repository up to the remote:
git push originThis sends our changes and merges them with the remote repository. If anything has changed on the remote since you last pulled, Git will refuse to push. You’ll have to pull again to make sure that you have the latest version.
If you take a look in the project directory in cPanel’s File Manager, you will see the HTML file you created is now on your server.
Automatically Deploy Code to Production with cPanel
Once you’ve finished editing your new site, you’ll want to deploy it to production. You could manually copy the site’s files to public_html, but cPanel Git Version Control can automate the deployment process.
In your local project folder, create a file called .cpanel.yml. This file tells cPanel which code to deploy and where to put it. In the simplest case, it looks like this.
—
deployment:
tasks:
- export DEPLOYPATH=/home/user/public_html/
- /bin/cp index.html $DEPLOYPATHHere we’re copying our index.html file into public_html. It’s unlikely that your deployment process is that simple, and you can learn more about the deployment file format in Guide to Git – Deployment.
Save the file, and push it to the remote repository.
git add . The period (.) tells Git to add all unstaged changes. Then we commit and push as before.
git commitgit push originWith the .cpanel.yml file in place, cPanel automatically deploys changes when they are pushed from local development machines to the server. If you would prefer to choose when the code is deployed, you can use a pull deployment method described in our Deployment documentation.
You can also manually deploy code at any time. Open Git Version Control in cPanel and click the Pull or Deploy tab. At the bottom of the page, there is a button called Deploy Head Commit. Clicking it deploys your latest code as described in the YAML configuration file.
This tab also displays information about the last successful deployment and the commit that kicked it off.
Streamlined Version Control and Deployment with cPanel
The workflow we’ve outlined here is perfect for simple Git repository hosting, local development, and automatic deployment for sites and apps managed by your cPanel account. However, Git is a powerful and complex tool that supports many different workflows. To learn more about Git and version control, take a look at these resources.
As always, if you have any feedback or comments, please let us know. We are here to help in the best ways we can. You’ll find us on Discord, the cPanel forums, and Reddit.