Moving Beyond FTP: Deploying with cPanel Git Version Control

The Problem with Manual Uploads

For many developers on shared hosting, the deployment process is a risky game of FTP drag-and-drop. Manually uploading files leads to "partial uploads" where some files update and others don't, leaving the site in a broken state. There is no version history on the server, and rolling back a bad change requires a manual backup of the public_html folder.

The takeaway: If your host supports it, cPanel Git Version Control allows you to treat your shared hosting account like a deployment target. By cloning a remote repository and using a declarative configuration file, you can move from manual file transfers to versioned, repeatable deployments.

How Git Version Control Integrates with cPanel

cPanel's Git tool is not a full CI/CD pipeline like GitHub Actions or GitLab CI, but it provides the essential bridge between a remote repository and the web root. It allows you to clone a repository (via HTTPS or SSH) into a directory on your account.

Crucially, it separates the repository directory (where the .git folder lives) from the deployment path (where the live website files are served). This prevents your internal Git metadata from being publicly accessible via the browser.

The Role of .cpanel.yml

To automate the movement of files from the cloned repository to the live folder, cPanel uses a file called .cpanel.yml. This file acts as a simple instruction set. When you trigger a deployment in the cPanel interface, the system reads this file and executes the defined tasks—typically copying specific files or directories to the document root.

Worked Example: Deploying a PHP Project

Assume you have a project on GitHub and a cPanel account with the username webuser. You want your files to land in /home/webuser/public_html.

1. Configure the .cpanel.yml

Create a file named .cpanel.yml in the root of your repository. Use the following configuration to copy your project files to the web root:

# .cpanel.yml
# Copy all files from the repo to the public_html directory
--- 
deployment:
  tasks:
    - cp -r * /home/webuser/public_html/

2. Connect the Repository

1. Log into cPanel and navigate to Git Version Control under the Files section.
2. Click Create.
3. Enter the Clone URL (e.g., https://github.com/username/repo.git).
4. Set the Repository Path to something outside the public folder, such as /home/webuser/repositories/my-site.
5. Click Create.

3. Execute the Deployment

Once cloned, the files exist in the repository path but not yet in public_html. To push them live:

1. In the Git Version Control list, click Manage next to your repository.
2. Go to the Pull or Deploy tab.
3. Click Update from Remote to pull the latest commits.
4. Click Deploy HEAD Commit. cPanel will now execute the cp command defined in your .cpanel.yml.

Trade-offs and Critical Limitations

While this is a massive upgrade over FTP, it has specific constraints that impact engineering decisions:

• No Build Step: cPanel Git is a copy mechanism, not a build system. If your project requires npm install or composer install, you must either run those commands via SSH (if enabled) or build the assets locally and commit the compiled files to the repo.
• Secret Management: Because .cpanel.yml copies files directly, any .env or config files committed to the repository will be copied into the web root. Never commit secrets to your repository. Create your production environment files manually on the server once.
• Manual Trigger: By default, this is a "pull" model. You must manually click deploy in cPanel unless your host supports Git webhooks to trigger the update.

Verification and Rollback

To verify the deployment worked, check the Deployment tab in the Git Version Control manager; it will show the timestamp of the last successful deploy. You can also check the file timestamps in the cPanel File Manager within public_html.

Rollback Procedure: If a deployment breaks the site, you can revert by following these steps:

1. In the Manage section of your repository, identify the commit hash of the last known working version.
2. Use the Deploy dropdown to select that specific commit rather than HEAD.
3. Click Deploy to overwrite the current live files with the previous version.