Overview

The Git™ Version Control feature facilitates the deployment of your cPanel-managed repositories. Typically, deployment involves transferring finalized code to a production environment. Various configurations allow for either automatic (push deployment) or manual (pull deployment) deployment of changes.

• For example, you could use deployment to make changes to your website locally, then automatically send them to a directory on your cPanel account.
• For more information about how to deploy changes, read our Git™ Version Control documentation.
• For more information about how to troubleshoot problems with this feature, read our Advanced Configuration and Troubleshooting documentation.
• For more information about Git commands, such as git push, git pull, or git commit, read our Common Git Commands documentation.

Requirements

For successful deployment, repositories must satisfy the following criteria:

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

Should a repository fail to meet these requirements, the system will neither display deployment information nor enable deployment functionality.

The deployment YAML file

The .cpanel.yml file dictates both the method and location for deploying modified files. A .cpanel.yml file must be committed to the top-level directory for every cPanel-managed repository intended for deployment. The .cpanel.yml files must adhere to the format presented in the examples below.

Important:

• Please note that the following files serve as examples only. You must modify them to align with your specific requirements, as they are not configured for successful repository deployment in their current form.
• Avoid using wildcard characters, such as an asterisk, for deploying all files. This practice could inadvertently deploy critical items like the .git directory, leading to significant issues.
• Refrain from using characters that are invalid within YAML files. For additional details, consult the Escaped Characters section of yaml.org’s YAML Specification.

Deploy individual files

The following .cpanel.yml file deploys the index.html and style.css files to the example account’s public_html directory:

1
2
3
4
5
6

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/example/public_html/
    - /bin/cp index.html $DEPLOYPATH
    - /bin/cp style.css $DEPLOYPATH

• Line 1 marks the commencement of the YAML file.
• Lines 2 and 3 introduce the deployment and tasks keys, respectively.
• Lines 4 through 6 define an array of BASH commands to be executed during deployment. Additional commands can be appended to this array as needed.

Note: To include comments within this file, prepend a line with the hash character (#).

Deploy an entire directory

The following .cpanel.yml file copies the images directory and all of its contents to the example account’s public_html directory:

1
2
3
4
5

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/example/public_html/
    - /bin/cp -R images $DEPLOYPATH

• Line 1 marks the commencement of the YAML file.
• Lines 2 and 3 introduce the deployment and tasks keys, respectively.
• Lines 4 and 5 define an array of BASH commands to be executed during deployment. Additional commands can be appended to this array as needed.

Note: To include comments within this file, prepend a line with the hash character (#).

Automatic or push deployment

Important: The Git™ Version Control interface within cPanel (cPanel » Home » Files » Git Version Control) automatically integrates a post-receive hook into all cPanel-managed repositories.

• Upon pushing changes directly to a cPanel-managed repository containing a .cpanel.yml file, the integrated hook automatically deploys these modifications.
• For further details, refer to Git’s githooks documentation.

In a push deployment scenario, a single git push command transmits changes from your local system to your cPanel-managed repository. The system subsequently executes the commands specified in your .cpanel.yml file. This setup facilitates the transfer of changes from the cPanel-managed repository to a production directory, such as the public files directory of your website.

Note: Manual deployment remains an option for redeploying your repository even without new modifications.

Manual or pull deployment

With pull deployment, the git push command transmits changes from your local system to a remote repository.

• When selecting Update from Remote within the Pull or Deploy tab of the Manage section in cPanel’s Git™ Version Control interface (cPanel » Home » Files » Git Version Control), the system fetches changes from the remote repository and applies them to the cPanel-managed repository.
• Upon clicking Deploy HEAD Commit, the system executes the commands defined in your .cpanel.yml file, transferring changes from the cPanel-managed repository to a production directory, such as the public files directory of your website.