Guide to Git – For System Administrators

Overview

The Git Version Control feature includes several changes from the Git default configuration. Additionally, we impose certain restrictions on cPanel-hosted repositories. This document also includes information that may assist you in troubleshooting cPanel users’ issues.

Restrictions

This feature imposes the following restrictions on cPanel-hosted repositories:

  • Currently, we only support a single remote repository for each local repository. To use multiple remote repositories, users must only use the command line.

  • 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
Note:

cPanel users cannot use the . or .. directory references when they enter the repository path in the interface.

Configuration changes

This feature alters the following configuration settings:

  • gc.auto — We have disabled Git’s garbage-collection setting for all cPanel-managed repositories.
  • receive.denyCurrentBranch — The system automatically sets this setting in each cPanel-managed repository’s configuration file to the updateInstead option.
    • The system ensures this configuration each time that you create a new repository via the VersionControl::create function.
    • The updateInstead option causes Git to automatically update the working tree whenever you push changes into the current branch.

This feature uses a cPanel-provided Git RPM. The Git RPM symlinks Git binaries in the /usr/local/cpanel/3rdparty/bin/ directory to the /usr/local/cpanel/3rdparty/lib/path-bin/ directory, to cause them to exist in the user’s default path.

Deployment

Important:

We strongly recommend that you only 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.
For more information about our suggested deployment configuration and how to set it up, read our Guide to Git – How to Set Up Deployment documentation.

Before deployment, repositories must meet 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. Also, it will disable deployment functionality.

Note:
  • The system adds a post-receive hook to all cPanel-managed repositories.
    • This hook will automatically run any commands in the .cpanel.yml file whenever changes deploy.
    • For more information, read Git’s githooks documentation.
  • The system stores deployment process-related historical data in an SQLite database within the /home/user/.cpanel/datastore/vc_deploy.sqlite file, where user represents the cPanel account name.

For instructions to set up deployment, read our Guide to Git – How to Set Up Deployment documentation.

For more information about deployment, read our Guide to Git – Deployment documentation.

SSH host key verification

When users clone a repository via SSH, the system will automatically check for the remote server’s public SSH key in the /home/user/.ssh/known_hosts file, where user represents the account’s username.

  • If the remote host is not registered with the system, the system will prompt the user to accept it. Then, it will 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.
    • For third-party remote hosts, check for announcements about public key updates. Most companies that host repositories make announcements about these changes.
    • For remote hosts that you control, consider whether recent events on your system have caused changes to the public key.
    • For any private repositories, make certain that you have performed the steps in our Guide to Git – Set Up Access to Private Repositories documentation.

The system also performs these checks each time that a user updates the repository’s information or attempts to pull changes from the repository via the cPanel interface.

Warning:

If you cannot verify the validity of the change, exercise caution, especially if the repository includes sensitive content. An altered SSH key may indicate a Man-in-the-Middle attack.

In order for users to see these warnings, you must 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).

Troubleshooting

If cPanel users experience problems with their repositories, use the following steps to troubleshoot them.

Note:

This feature logs messages and errors to the following locations:

  • /usr/local/cpanel/logs/error_log — Errors and stack traces.
  • /home/username/.cpanel/logs/user_task_runner.log — Queue-related items.
  • /home/username/.cpanel/logs/vc_TIMESTAMP_git_create.log — Creation-related issues, where TIMESTAMP represents the time of the operation.
  • /home/username/.cpanel/logs/vc_TIMESTAMP_git_deploy.log — Deployment-related issues, where TIMESTAMP represents the time of the operation.

Missing repositories

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.

Missing branches

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.

Cloned repositories

While the system clones the remote repository, cPanel’s Git Version Control interface (cPanel >> Home >> Files >> Git Version Control) will only display the repository name and path.

When users clone a repository, the system clones it via a queued process that runs as that cPanel user. Clones can require a large amount of time, which depends on the size of the repository to clone.

  • While the clone process runs, cPanel’s Git Version Control interface (cPanel >> Home >> Files >> Git Version Control) will only display the repository name, repository path, and a progress indicator. Additionally, the system will temporarily disable most of the management functionality for that repository.

  • The process_user_tasks binary runs as the cPanel user to process each clone, and the queue for each user exists in their .cpanel/user_tasks/ directory. To resolve issues with clones, stop the process and delete the directory.

SSH access

If users experience problems with SSH access, ensure that the server and the users’ accounts include the following settings and configurations:

  • 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 in to the account.

  • The Shell Access setting is enabled for the account in WHM’s Modify an Account interface (WHM >> Home >> Account Functions >> Modify an Account).

  • The 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, ensure that the user correctly configured their public SSH keys in cPanel’s SSH Access interface (cPanel >> Home >> Security >> SSH Access).

Note:

If a user attempts to clone a remote repository via SSH and receives errors about a refused connection, perform one of the following actions:

  • 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.