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

Description

This function retrieves the status of deployment tasks.

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.

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/retrieve


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.
 
// Retrieve deployment data.
$retrieve = $cpanel->uapi(
    'VersionControlDeployment', 'retrieve',
);


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.
 
# Retrieve deployment data.
my $retrieve = $cpliveapi->uapi(
    'VersionControlDeployment', 'retrieve', 
);


Note:

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

 

 cPanel Template Toolkit
<!-- Retrieve deployment data. -->
[% data = execute( 
   'VersionControlDeployment', 'retrieve', 
); %]


Note:

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

 

 Command Line
uapi --user=username VersionControlDeployment retrieve


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/5aea11e886a5d8",
              "repository_root": "/home/user/public_html/example",
              "log_path": "/home/user/.cpanel/logs/vc_1525289448.784903_git_deploy.log",
              "sse_url": "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
              "timestamps": {
                  "queued": 1525289448.83553,
                  "active": 1525289449.2957,
                  "succeeded": 1525289479.77638
              },
              "repository_state": {
                  "branch": "master",
                  "identifier": "e39946d9eed69b9ca5a7af510494165670465828",
                  "date": "1410277881",
                  "author": "User Name <user.name@example.com>",
                  "message": "This is a commit."
              }
          },
          {
              "deploy_id": 13,
              "task_id": "00000000/7b0ec8dd4c429c",
              "repository_root": "/home/user/public_html/example2",
              "log_path": "/home/user/.cpanel/logs/vc_1525289545.795720_git_deploy.log",
              "sse_url": "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
              "timestamps": {
                  "queued": 1525289545.16293,
                  "active": 1525289545.3592,
                  "canceled": 1525289575.44234
              },
              "repository_state": {
                  "branch": "master",
                  "identifier": "F86326d9eed69b9ca5a7af510494165670468216",
                  "date": "1410277802",
                  "author": "User Name <user.name@example.com>",
                  "message": "This is another commit."
              }
          }
      ]
   },
   "status":1,
   "metadata":{  

   },
   "messages":null
}


Note:

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

Parameters

This function does not accept parameters. 

Returns

ReturnTypeDescriptionPossible valuesExample

hash

An unnamed hash of deployment task data.

The function returns this value in the unnamed hash.

This hash includes the deploy_id, task_id, repository_root, and log_path returns and the timestamps hash.

deploy_id

string

The deployment ID number.

The function returns this value in the unnamed hash.

A valid deployment ID.13

task_id

string

The Task Queue system's task ID number.

The function returns this value in the unnamed hash.

A valid task ID.

00000000/5aea11e886a5d8


repository_root

string

The repository's directory.

The function returns this value in the unnamed hash.

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.

The function returns this value in the unnamed hash.

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_1525289448.759720_git_deploy.log

sse_url

stringThe SSE interface to track the progress of the deployment process.A valid SSE URL./sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0

timestamps

hash

A hash of timestamps for the deployment process.

The function returns this hash in the unnamed hash.

This hash includes the queued and active returns and one of the succeeded, failed, or canceled returns.

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.

1525289448.83553

active

string

The time at which the system started the deployment process.

The function returns this value in the timestamps hash.

A valid timestamp, in Unix epoch time.

1525289448.83553

succeeded

string

The time at which the deployment process finished successfully.

Note:

The function only returns this value if the deployment process succeeded.

The function returns this value in the timestamps hash.

A valid timestamp, in Unix epoch time.

1525289448.83553

failed

string

The time at which the deployment process failed.

Note:

The function only returns this value if the deployment process failed.

The function returns this value in the timestamps hash.

A valid timestamp, in Unix epoch time.

Remember:

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.

1525289448.83553

canceled

string

The time at which the system canceled the deployment process.

Note:

The function only returns this value if the system canceled the deployment process.

The function returns this value in the timestamps hash.

The time at which the system canceled the deployment process, in Unix epoch time.

Remember:

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.

1525289448.83553

repository_state

hash

A hash of information about the repository's state at the time of deployment.

The function returns this hash in the unnamed hash.

This hash includes the branch, identifier, date, author, and message returns.

branch

string

The repository's current branch.

The function returns this hash in the repository_state hash.

A valid branch name.master

identifier

string

The identifier (SHA-1 value) for the most-recent commit.

The function returns this hash in the repository_state hash.

A valid SHA-1 value.2fd4e1c67a2d28fced849ee1bb76e7391b93eb12

date

string

The timestamp for the most-recent commit.

The function returns this hash in the repository_state hash.

A valid time, in Unix time format.1410277881

author

string

The most-recent commit's author's name and email address.

The function returns this hash in the repository_state hash.

The author's name and email address as they exist in the user's Git configuration files.Jane Doe <jane.doe@example.com>

message

string

The commit message.

The function returns this hash in the repository_state hash.

A valid string.This is a commit.