Child pages
  • UAPI Functions - VersionControlDeployment::create
Skip to end of metadata
Go to start of metadata

Description

This function deploys the changes from a cPanel-managed repository.

Important:

  • The system logs messages for this function in the ~/.cpanel/logs/vc_TIMESTAMP_git_deploy.log file, where TIMESTAMP represents the time in Unix epoch time.
  • The system pulls changes with the --ff-only option and will only succeed if the branch's HEAD commit is up-to-date or Git can fast forward it.
  • For more information about our suggested deployment configuration and how users can 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 and will disable deployment functionality.

For more information, read our Guide to Git - Deployment documentation.

Examples  


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/VersionControlDeployment/create?repository_root=%2Fhome%2Fuser%2Fexample


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Initiate deployment
$create = $cpanel->uapi(
    'VersionControlDeployment', 'create',
     array(
        'repository_root'    => '/home/user/example';
     )
);


Note:

For more information, read our Guide to the LiveAPI System.

 

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Initiate deployment
my $create = $cpliveapi->uapi(
    'VersionControlDeployment', 'create',    {
        'repository_root'    => '/home/user/example',
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 

 cPanel Template Toolkit
<!-- Initiate deployment -->
[% data = execute( 
   'VersionControlDeployment', 'create', {
        'repository_root'    => '/home/user/example',
   } 
); %]


Note:

For more information, read our Guide to Template Toolkit documentation. 

 

 Command Line
uapi --user=username VersionControlDeployment create repository_root=/home/user/example


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{  
   "errors":null,
   "data":{
      "deploy_id": 12,
      "task_id": "00000000/5a9ec8dd4c345d",
      "repository_root": "/home/user/public_html/example",
      "log_path": "/home/user/.cpanel/logs/vc_1525289545.785367_git_deploy.log"
      "sse_url": "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
      "timestamps": {
          "queued": "1525289545.16293"
      },
   },
   "status":1,
   "metadata":{  

   },
   "messages":null
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
repository_rootstring

Required

The repository's directory.

A valid absolute path to a directory that contains a cPanel-managed repository.

/home/user/public_html/example

 

Returns

ReturnTypeDescriptionPossible valuesExample
deploy_idstring

The deployment ID number.

A valid deployment ID.12

task_id

string

The Task Queue system's task ID number.

A valid task ID.00000000/5a9ec8dd4c345d

repository_root

string

The repository's directory.

A valid absolute path to a directory that contains a cPanel-managed repository./home/username/example

log_path

string

The path to the task's log file.

A valid absolute path to the ~/.cpanel/logs/vc_TIMESTAMP_git_deploy.log file, where TIMESTAMP represents the time in Unix epoch time./home/user/.cpanel/logs/vc_1525289545.785367_git_deploy.log
sse_urlstringThe SSE interface to track the progress of the deployment process.A valid SSE URL./sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0
timestampshashA hash of timestamps for the deployment process.This hash includes the queued return.

queued

string

The time at which the deployment process entered the task queue.

The function returns this value in the timestamps hash.

A valid timestamp, in Unix epoch time.1525289545.16293