Skip to main content

How to Configure SSH Key Authentication for Use with cPanel Git™ Version Control

Austin Lowery
  • Updated

Introduction

This guide provides a step-by-step explanation for configuring key authentication to access a remote Git repository from your cPanel account.

You would use this guide if:

  • You need to clone a remote Git repository into your cPanel account and the remote repository requires authentication.
  • You need to pull changes from a remote Git repository to the repository that is hosted in your cPanel account and the remote repository requires authentication.
  • You see a Permission Denied Error in the cPanel Git™ Version Control icon

 

Procedure

Option #1 - Generate a New Private and Public Key Pair

  1. Login to your cPanel server via SSH as your cPanel user, or use the Terminal icon in the cPanel account to access the command line.
  2. Run the following command to generate the private and public keys that you will use to authenticate to your remote Git repository.
    IMPORTANT: When this command prompts you to enter a passphrase, press enter to skip adding a passphrase. cPanel Git™ Version Control is not compatible with keys that use a passphrase.
    ssh-keygen -t ed25519 -C "youremailaddress@domain.tld DAY-MONTH-YEAR" -f ~/.ssh/my_key
    • The -C flag specifies a comment to add to your public key. This can be helpful for you to identify which public keys you have authorized in a remote system, so it is common practice to put your email address and the date as the comment. You may put any arbitrary string as the comment, or even omit it entirely if you prefer.
    • The -f flag determines what name will be used for your private and public keys. If you omit the -f flag entirely, your keys will be created at ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub. When specifying the -f flag, there is no need to specify the public key name as it will always be the same name as the private key, but with .pub appended to the end.
  3. Create the ssh configuration file if it does not yet exist: 
    touch ~/.ssh/config
  4. Update the permissions of the ~/.ssh/config file to 0600 as is required: 
    chmod 0600 ~/.ssh/config
  5. The ownership should already be set to the cPanel user's if you're doing this as the cPanel user, but it is ideal to ensure that is the case: 
    chown cpanelusername:cpanelusername ~/.ssh/config
  6. Open ~/.ssh/config  with the text editor of your choice and enter a configuration formatted according to the following example. 
    Host remote-git-repo-domain.tld
        IdentityFile ~/.ssh/my_key
    NOTE: If you want to use this private key when connecting to any remote host via SSH, you may use an asterisk character as the Host instead of a specific domain name: * 
    Otherwise, use the domain name of your remote Git repository provider which would be found within the SSH repository URL that you obtain in step 7 below.
    Be sure to also use the path to your private key that you generated in step 2 for the IdentityFile.
  7. Save the file
  8. Login to the management interface of your remote Git repository
  9. Obtain the SSH repository URL that you would like to clone your repository from.
  10. While you are in the management interface of your remote Git repository, ensure that you configure the PUBLIC key within the remote system so that it is authorized for access. To do this cat the contents of the public key from your cPanel Terminal or SSH session with the following command: (be sure to use the path to your own public key that you generated in step 2) 
    cat ~/.ssh/my_key.pub
    Then paste the output from that command into the remote Git repository interface where key authentication is supposed to be configured.
  11. Back in your cPanel Terminal or SSH session, perform a test clone of the repository to see if authentication will work properly. The following examples use the --bare option in case you have a large repository and you do not want to download all of the data. Use the SSH repository URL that you obtained from your Git provider from step 7 above.
    # Github style SSH clone URL
    git clone --bare --verbose git@github.com:githubusername/repo-name.git -- ~/test-clone-destination-dir

    # Standard SSH clone URL
    git clone --bare --verbose ssh://remoteusername@remote-git-repo-domain.tld:SSHPort/path/to/repo.git/ -- ~/test-clone-destination-dir
  12. If authentication did not work, you should double check your ~/.ssh/config, and troubleshoot the SSH access to the remote server. You may also need to check the permissions and ownership of the ~/.ssh directory any any files contained within it. If the remote Git host supports direct SSH logins (Github does not) you may try using an SSH command similar to the following to debug the authentication issue: 
    ssh -vvv -p SSHPort remoteusername@remote-git-repo-domain.tld
  13. If authentication was successful, you may then configure your repository within the cPanel Git™ Version Control icon.

 

Option #2 - Use Your Existing Private and Public Key Pair

NOTE: Keys that are passphrase protected are not compatible with cPanel Git™ Version Control. If your existing keys require a passphrase, please make use of the section labeled: Option #1 - Generate a New Private and Public Key Pair to learn how to generate a compatible set of keys.

This section would be used if you are already familiar with how Private and Public keys work, and you have your own set of keys that you want to use to authenticate to the remote repository.

  1. Login to the management interface of your remote Git repository
  2. Obtain the SSH repository URL that you would like to clone your repository from.
  3. While you are in the management interface of your remote Git repository, ensure that you have already configured the PUBLIC key within the remote system so that it is authorized for access. The public key that you configure in the remote system should be the one that was generated at the same time as the private key that you intend to use. NOTE: Keys that were generated with a passphrase are not compatible with cPanel Git™ Version Control. Generate a new set of keys without a passphrase if needed.
  4. Upload your PRIVATE key to the ~/.ssh directory of your cPanel account. This can be done via the File Manager icon in cPanel, FTP, SFTP, or you can copy and paste it in via SSH if you know how.
  5. Login to your cPanel server via SSH as your cPanel user, or use the Terminal icon in the cPanel account to access the command line.
  6. Run the following command to check the permissions and ownership of the .ssh directory
    NOTE: Pay special attention to the example output. Notice that the Uid and Gid are the cPanel username, and the permissions are set to 0700.
    [cpanelusername@hostname ~]$ stat ~/.ssh | grep Access -m 1
    Access: (0700/drwx------) Uid: ( 1002/cpanelusername) Gid: ( 1008/cpanelusername)
  7. If the permissions and ownership do not follow the example above, you may use the following commands to fix this.
    chmod 0700 ~/.ssh
    chown cpanelusername:cpanelusername
    NOTE: If the ownership is incorrect, you will need to run the chown command as the root user, or ask your hosting provider to fix the ownership if you do not have root access.
  8. Next, locate the PRIVATE key that you have uploaded to the server and ensure the permissions are set to 0600, and the Uid and Gid ownership are set to the cPanel user as is shown in the following example. Please take note that  the name of this example key is my_key. Your key file can be named whatever you want it to be. However, use of non OpenSSH key formats such as .ppk files may complicate the authentication process in a way that is outside of the scope of this guide. You must be able to troubleshoot complications that arise from using your chosen custom key. If you run into complications with your custom key use the section of this guide that is labeled Option #1 - Generate a New Private and Public Key Pair to learn how to generate a compatible set of keys. 
    [cpanelusername@hostname ~]$ stat ~/.ssh/my_key | grep Access -m 1
    Access: (0600/-rw-------) Uid: ( 1002/cpanelusername) Gid: ( 1008/cpanelusername)
  9. Create the ssh configuration file if it does not yet exist: 
    touch ~/.ssh/config
  10. Ensure that the permissions and ownership of ~/.ssh/config match the following: 0600 and owned by the cPanel user: 
    [cpanelusername@hostname ~]$ stat ~/.ssh/config | grep Access -m 1
    Access: (0600/-rw-------) Uid: ( 1002/cpanelusername) Gid: ( 1008/cpanelusername)
  11. Open ~/.ssh/config  with the text editor of your choice and enter a configuration that follows the format of the following example.
    Host remote-git-repo-domain.tld
        IdentityFile ~/.ssh/my_private_key
    NOTE: If you want to use this private key when connecting to any remote host via SSH, you may use an asterisk character as the Host instead of a specific domain name: *
    Otherwise, use the domain name of your remote Git repository provider.
  12. Save the file with your new configuration.
  13. Run a test clone of the repository to see if authentication will work properly. The following examples use --bare in case you have a large repository and you do not want to download all of the data. This step is only for testing to ensure that authentication works as desired. Use the SSH repository URL that you obtained from your Git provider in step 2 from above.
    # Github style SSH clone URL
    git clone --bare --verbose git@github.com:githubusername/repo-name.git -- ~/test-clone-destination-dir

    # Standard SSH clone URL
    git clone --bare --verbose ssh://remoteusername@remote-git-repo-domain.tld:SSHPort/path/to/repo.git/ -- ~/test-clone-destination-dir
  14. If authentication did not work, you should double-check your ~/.ssh/config, and troubleshoot the SSH access to the remote server. If the remote host supports direct SSH logins (Github does not) you may try using an SSH command similar to the following to debug the authentication issue: 
    ssh -vvv -p SSHPort remoteusername@remote-git-repo-domain.tld
  15. If authentication was successful, you may then configure your repository within the cPanel Git™ Version Control icon.

Related articles