As a system administrator, chances are that you will likely run into issues when cPanel users want to host Git Repositories on a cPanel account.
Below are some of the trouble-shooting tips that you can to isolate whatever issue it is that they are running into.
cPanel Imposed Restrictions
Git’s configuration files are plain-text that you can edit manually to change the default behavior to what you may want.
cPanel though has made several changes from the Git™ default configuration and also imposed some restrictions on cPanel-hosted repositories.
For example, users cannot include whitespace or the following characters in repository paths:
\ * | " ' < > & @ ` $ { } [ ] ( ) ; ? : = % #
Users cannot use this feature to create, delete, or view repositories in the following cPanel-controlled directories:
.cpanel .cphorde .htpasswds .ssh .trash access-logs cgi-bin etc logs perl5 mail spamassassin ssl tmp var
It is worth bearing in mind that cPanel users cannot use the . or .. directory references when they enter the repository path in the interface.
Multiple remote repositories are ONLY possible via the command line.
About Git’s garbage-collection setting, this has been disabled for all cPanel-managed repositories.
The "git gc" command ("gc" stands for garbage collection) is a repository maintenance command given that Git repositories accumulate various types of garbage.
Executing git gc is literally telling Git to clean up the mess it's made in the current repository.
It is also worth noting that given that the system automatically sets "receive.denyCurrentBranch" in each cPanel-managed repository’s configuration file to the "updateInstead", Git will automatically update the working tree whenever you push changes into the current branch.
Watch out for this if a user isn't allowed to git push to cPanel account.
When receive.denyCurrentBranch is set to updateInstead, a push that tries to update the branch that is currently checked out is accepted only when the index and the working tree exactly matches the currently checked out commit, in which case the index and the working tree are updated to match the pushed commit.
"receive.denyCurrentBranch" if set to true or "refuse" will deny a ref update to the currently checked out branch of a non-bare repository.
That is, setting receive.denycurrentbranch to updateinstead and pushing into the current branch when the working tree and the index is truly clean is supposed to reset the working tree and the index to match the tree of the pushed commit.
Typically, you should have a bare repository on the server, not one with a checked-out working tree.
To sort this issue out, either create a bare git repo or convert an existing non-bare repo to a bare one by recloning it as a bare repo:
git clone --bare old-repo
cPanel-provided Git RPM symlinks Git binaries in the /usr/local/cpanel/3rdparty/bin/ directory to the /usr/local/cpanel/3rdparty/lib/path-bin/ directory in order for them to exist in the user’s default path.
It is strongly recommended to deploy changes from a remote repository or a clone of it on your local computer.
You should not directly change the cPanel-managed repository’s contents.
Before deployment, ensure that the repositories met the following requirements:
- a valid checked-in .cpanel.yml file in the top-level directory.
- one or more local or remote branches.
- a clean working tree.
If a repository does not meet these requirements, the system will not display deployment information and will also disable deployment functionality.
cPanel Git & SSH
Regarding SSH host key verification, it is recommended that you enable the Enable strict SSH host key checking setting in the Security section of WHM’s Tweak Settings interface (WHM >> Home >> Server Configuration >> Tweak Settings) which helps protect against man-in-the-middle attacks.
When you enable this setting, every remote system that is connected to via SSH must have a valid key in the /etc/ssh/ssh_known_hosts file.
If you set this value to "dns", the remote system has SSHFP records in a DNSSEC-signed zone, and the local system uses EDNS0 resolving, use these records to validate the remote system.
If you set this value to "dns" but the system does not use SSHFP records in a DNSSEC-signed zone or does not use ENDS0 resolving, the system will act as though the option were set to "enabled".
cPanel systems use this to automatically check for the remote server’s public SSH key in the /home/user/.ssh/known_hosts file when users clone a repository via SSH.
These are the checks each time that a user updates the repository’s information or attempts to pull changes from the repository via the cPanel interface:
- if the remote host is not registered with the system, the system will prompt the user to accept it, then add it to the /home/user/.ssh/known_hosts file where "user" represents the account’s username.
- if the remote host is already registered, the system will display a confirmation message.
- if the remote host’s public key has changed, the system will display a warning.
If you are using a third-party remote host and run into validation issue, check for announcements about public key updates.
If it is a remote hosts that you control, consider whether recent events on your system have caused changes to the public key.
If you are unable to verify the validity of that change, this may indicate an altered SSH key which in turn may indicate a Man-in-the-Middle attack.
If users experience problems with SSH access, check to ensure that the server and the users’ accounts include the following settings and configurations:
- Check to ensure that Port 22 is publicly accessible. If the server uses a nonstandard Git port, use the ssh -p port command, where port represents the port number, to SSH into the account.
- Check that Shell Access setting is enabled for the account in WHM’s Modify an Account interface (WHM >> Home >> Account Functions >> Modify an Account).
- Check that SSH Access & Terminal feature is enabled for the user’s feature list in WHM’s Feature Manager interface (WHM >> Home >> Packages >> Feature Manager).
If none of these solutions fix the issue, visually verify to ensure that the user correctly configured their public SSH keys in cPanel’s SSH Access interface (cPanel >> Home >> Security >> SSH Access).
If a user attempts to clone a remote repository via SSH and receives errors about a refused connection:
- Clone the repository via HTTPS in a read-only configuration.
- Register the cPanel account’s SSH key pair with the remote repository’s host as a deployment key.
Repos
If one of your cPanel users experience problems with their repositories, use the following steps to troubleshoot them.
- Errors and stack traces: /usr/local/cpanel/logs/error_log
- Queue-related items: /home/username/.cpanel/logs/user_task_runner.log
- Creation-related issues, where TIMESTAMP represents the time of the operation: /home/username/.cpanel/logs/vc_TIMESTAMP_git_create.log
- Deployment-related issues, where TIMESTAMP represents the time of the operation: /home/username/.cpanel/logs/vc_TIMESTAMP_git_deploy.log
If repositories exist on the command line but do not display in cPanel’s Git Version Control interface (cPanel >> Home >> Files >> Git Version Control), the issue may occur because the feature ignores repositories that users created on the command line.
If the expected list of branches does not display in cPanel’s Git Version Control interface (cPanel >> Home >> Files >> Git Version Control), the issue may be due to the following causes:
- the branches exist in the copies of the repository on your local computer or remote repository host, but do not exist within the cPanel-managed repository.
- the repository is a bare repository. Bare repositories do not include branches.
