Automating Git deployment tasks with the .cpanel.yml file

The .cpanel.yml file defines the tasks that cPanel's Git deployment runs. It must be versioned in the repository root, with exactly that name.

If you would rather set up scripts, releases and automation from the client area, see Deploy+.

Example for two static files

This example copies two files from the repository to a test folder that must already exist. Replace the path with yours and first check that it does not contain files with those names that you want to keep:

---
deployment:
  tasks:
    - /bin/cp -- index.html style.css /home/usuario_cpanel/public_html/pruebas/

The copy may overwrite the two destination files. It does not synchronise a whole website, does not delete old files and does not change both files atomically. For several dependent operations, call a script with error checking, as in the Laravel example.

Push and pull: when it runs

Push to the cPanel repository: cPanel can run the tasks through its hook if the repository meets the deployment requirements. Confirm the repository and the branch you are pushing code to.

Pull from GitHub or another remote: in Git Version Control > Manage > Pull or Deploy, Update from Remote updates the clone. You then need to use Deploy HEAD Commit to run .cpanel.yml. A push to GitHub does not automatically start this process in cPanel.

Trigger it from the API or cron

For a repository already managed by cPanel:

/usr/local/cpanel/bin/uapi --output=jsonpretty VersionControlDeployment create \
  repository_root='/home/usuario_cpanel/repositories/proyecto'

The call requests a deployment of the code that is in the repository; it does not replace the step of updating from the remote. Check result.status and follow the log or the task until you know its final result.

Do not add the call to cron without a control that prevents overlaps for the whole run. A lock that is released when the API returns the queued task may end before the deployment does.

Check and undo

After the deployment, check the logs, the commit and the content being served. A task may have changed data before failing; do not assume everything has been undone.

Prepare a way to recover overwritten content and keep persistent files separately. For database changes, define a specific rollback: going back to a commit does not recover data a task has deleted.