LogoفارسیFA

Guide to Git Advanced Configuration and Troubleshooting

This guide explains the advanced configuration changes, restrictions, deployment behavior, SSH host key verification, and troubleshooting methods for Git repositories managed through cPanel. It is designed for system administrators who need deeper insight into how Git operates within the cPanel environment.

Git cPanelGit TroubleshootingGit Configuration

~4 min read • Updated Feb 21, 2026

1. Overview


The Git Version Control feature in cPanel includes several modifications from Git’s default configuration. Additionally, cPanel imposes restrictions on hosted repositories. This guide is intended for system administrators and provides configuration details and troubleshooting information for common issues encountered by cPanel users.


2. Restrictions


The following restrictions apply to cPanel-hosted Git repositories:


  • Only one remote repository is supported per local repository. Multiple remotes require command-line usage.
  • Repository paths cannot contain whitespace or the following characters:

\ * | " ' < > & @ ` $ { } [ ] ( ) ; ? : = % #


Users cannot create, delete, or view repositories in these cPanel-controlled directories:


.cpanel, .cphorde, .htpasswds, .ssh, .trash, access-logs, cgi-bin, etc, logs, perl5, mail, spamassassin, ssl, tmp, var


Note: The . and .. directory references are not allowed in repository paths.


3. Configuration Changes


  • gc.auto — Git’s garbage collection is disabled for all cPanel-managed repositories.
  • receive.denyCurrentBranch — Automatically set to updateInstead.

The updateInstead option updates the working tree automatically when pushing to the current branch.


cPanel uses a custom Git package that symlinks Git binaries into /usr/local/cpanel/3rdparty/bin/, ensuring they are available in the user’s default path.


4. Deployment


Important: We strongly recommend deploying only from a remote repository or a local clone. Do not modify the cPanel-managed repository directly.


Deployment requirements:


  • A valid .cpanel.yml file in the top-level directory
  • One or more branches
  • A clean working tree

The system adds a post-receive hook to all cPanel-managed repositories. This hook runs any commands in the .cpanel.yml file whenever changes deploy.


Deployment history is stored in:


/home/user/.cpanel/datastore/vc_deploy.sqlite


For setup instructions, refer to the Set Up Deployment documentation.


5. SSH Host Key Verification


When cloning via SSH, the system checks the remote host’s public key in:


/home/user/.ssh/known_hosts


Behavior:

  • If the host is new → user is prompted to accept it
  • If already registered → confirmation message
  • If the key has changed → security warning

For third-party hosts, check for public key update announcements. For private repositories, ensure SSH access is configured correctly.


Warning: If the key change cannot be verified, it may indicate a Man-in-the-Middle attack.


To display these warnings, enable Enable strict SSH host key checking in WHM’s Tweak Settings.


6. Troubleshooting


If users experience issues with their repositories, use the following steps.


6.1 Log File Locations


  • /usr/local/cpanel/logs/error_log — Errors and stack traces
  • /home/username/.cpanel/logs/user_task_runner.log — Queue-related items
  • vc_TIMESTAMP_git_create.log — Repository creation issues
  • vc_TIMESTAMP_git_deploy.log — Deployment issues

6.2 Missing Repositories


If a repository exists on the command line but not in the cPanel interface, it may have been created manually. The interface ignores such repositories.


6.3 Missing Branches


  • Branches may exist only on the local machine or remote host, not in the cPanel-managed repository.
  • The repository may be a bare repository, which contains no branches.

6.4 Cloned Repositories


Cloning occurs through a queued process and may take time. During cloning, the interface displays only the repository name, path, and progress indicator.


To resolve clone issues:


  • Stop the process
  • Delete the .cpanel/user_tasks/ directory

6.5 SSH Access Issues


Verify the following:

  • Port 22 is publicly accessible
  • Shell Access is enabled in WHM
  • SSH Access & Terminal is enabled in Feature Manager
  • Public SSH keys are correctly configured in cPanel

Note: If SSH cloning fails:

  • Clone via HTTPS in read-only mode
  • Register the SSH key pair as a deployment key

Conclusion


This guide helps system administrators understand advanced Git behavior in cPanel, including configuration changes, restrictions, deployment mechanics, SSH verification, and troubleshooting steps. Proper knowledge of these areas ensures smooth repository management and faster issue resolution.


Written & researched by Dr. Shahin Siami

Next Article