Child pages
  • UAPI Functions - VersionControl::update
Skip to end of metadata
Go to start of metadata

Description

This function modifies a Git™ repository's basic settings.

  • In cPanel & WHM version 72, this function pulls changes from the remote repository each time that you call the function.
  • In cPanel & WHM version 74 and later, this function only pulls changes from the remote repository if you specify a branch value.
  • For more information about support for version control in cPanel & WHM, read our Git Version Control and Guide to Git documentation. 

Note:

You cannot modify the type, repository_root, or url values for existing repositories.

Examples 


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/VersionControl/update?name=example&repository_root=%2Fhome%2Fuser%2Fpublic_html%2Fexample&branch=master&source_repository%3D%27%7B%22remote_name%22%3A%22origin%22%2C%22%7D%27


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.
 
// Update a repository.
$source_repositoryObj -> remote_name = "origin";
$update = $cpanel->uapi(
    'VersionControl', 'update',
     array(
        'name'               => 'example',
        'repository_root'    => '/home/user/public_html/example',
        'branch'             => 'master',
        'source_repository'  => json_encode($source_repositoryObj);
     )
);


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.
 
# Update a repository.
my $update = $cpliveapi->uapi(
    'VersionControl', 'update',    {
        'name'               => 'example',
        'repository_root'    => '/home/user/public_html/example',
        'branch'             => 'master',
        'source_repository'  => {
           "remote_name" => "origin",
        },
   }
);


Note:

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

 

 cPanel Template Toolkit
<!-- Update a repository. -->
[% data = execute( 
   'VersionControl', 'update', {
        'name'               => 'example',
        'repository_root'    => '/home/user/public_html/example',
        'branch'             => 'master',
        'source_repository'  => {
           "remote_name" : "origin",
        },
   } 
); %]


Note:

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

 

 Command Line
uapi --user=username VersionControl update name=example repository_root=/home/user/public_html/example branch=master source_repository='{"remote_name":"origin"}'


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":{
      "name":"example",
      "type":"git", 
      "repository_root":"/home/user/example",
      "branch":"master",
      "deployable":"1",
      "available_branches": [
         "master"
         ],
      "last_update": {
         "date": "1410277881",
         "identifier": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
         "author": "Jane Doe <jane.doe@example.com>",
         "message": "I'm committing some particularly cromulent code."
      },
      "last_deployment": {
         "deployment_date": "1410277881",
         "repository_state": {
             "date": "1410277881",
             "identifier": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb121",
             "author": "User Name <user.name@example.com>",
             "message": "I'm committing some particularly cromulent code."
         }
      },
      "clone_urls":{  
         "read_write":[  
            "ssh://user@example.com/home/user/example"
         ],
         "read_only":[  
            "https://user@example.com/home/user/example"
         ]
      },
      "tasks": [
         {  
            "id": "00000000/5a9ec8dd4c345d",
            "subsystem": "VersionControl",
            "action": "create"
            "args": {
                "repository_root": "/home/user/example"
            }
         }
      ]

   },
   "status":1,
   "metadata":{  

   },
   "messages":null
}


Note:

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

Parameters

Notes:

  • You must include the repository_root parameter in order to identify the repository to update. 
  • All other input parameters are optional. Use them to assign the new values to the account. If you do not include a parameter or specify its existing value, no change will occur. 
ParameterTypeDescriptionPossible valuesExample
repository_rootstring

Required

The directory that contains the repository to update.

A valid absolute path to a directory that contains a repository.

/home/user/public_html/example

 

namestring

The repository's new display name.

If you do not specify a value, the function does not update this parameter.

A valid string.example
branchstring

The new branch to use.

Remember:

In cPanel & WHM version 74 and later, the function pulls changes from the remote repository if you specify a branch value.

If you do not specify a value, the function does not update this parameter.

A valid branch name.master
source_repositoryhash

A hash of information about the source repository.

Important:

You cannot modify the source repository's URL. 

If you do not specify a value, the function does not update this parameter.

This hash contains the remote_name parameter.

Important:

You must JSON-encode the contents of this hash. 

 

remote_name

JSON string

The source repository's name.

If you do not specify a value, the function does not update this parameter.

Include this value in the source_repository hash.

A valid JSON-encoded string.origin

Returns

ReturnTypeDescriptionPossible valuesExample

name

string

The repository's display name.


A valid string.

example

type

string

The repository type.


git is the only possible value.git

repository_root

string

The directory that contains the repository.


A valid absolute path to a directory that exists within the user's home directory.

/home/user/public_html/example

branch

string

The repository's current branch.


  • A valid branch name.
  • null — The system has not finished the clone process for the repository, no local branches exist, or the repository is a bare repository.
master

 

deployable

Boolean

Whether the system could deploy the repository.

Note:

We added this return in cPanel & WHM version 74.

  • 1 — Can deploy.
  • 0 — Cannot deploy.
1

source_repository

hash

A hash of information about the source repository.

Note:

The function only returns this hash if you cloned a source repository.

The function returns this hash in the repository's hash.

This hash contains the remote_name and url parameters.

Important:

You must JSON-encode the contents of this hash. 

 

remote_name

JSON string

The source repository's name.

The function returns this value in the source_repository hash.

A valid JSON-encoded string.origin

url

JSON string

The source repository's clone URL.

Note:

If you include the source_repository hash, you must specify a url value.

The function returns this value in the source_repository hash.

 A valid JSON-encoded clone URL.ssh://clone.domain.com/cloneme 

available_branches

array of strings

An array of available branches for the repository.


  • An array of local and remote branch names that exist for the cloned or existing repository.
  • An empty array, if no branches exist.
  • null, if the repository is a bare repository.
master

last_update

hash

A hash of information about the most-recent (HEAD) commit for the current branch.

Note:

This hash's information resembles the output of the git log -1 command.

The function returns this hash in the repository's hash.

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

Important:

  • If the repository does not include any commits, the function returns a null value instead of a hash.
  • The system may require a large amount of time to clone larger repositories. Until this process finishes, HEAD information is unavailable.
                

date

string

The timestamp for the most-recent commit.

The function returns this value in the last_update hash.

A time, in Unix time format.1410277881

identifier

string

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

The function returns this value in the last_update hash.

A valid SHA-1 value.2fd4e1c67a2d28fced849ee1bb76e7391b93eb12

author

string

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

The function returns this value in the last_update 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 value in the last_update hash.

A valid string.I'm committing some particularly cromulent code.

last_deployment

hash

A hash of information about the commit that the system most recently deployed.

Note:

We added this hash in cPanel & WHM version 74.

The function returns this hash in the repository's hash.

This hash includes the deployment_date return and the repository_state hash.

Note:

If no deployment information exists, the function returns a null value.

                

deployment_date

string

The timestamp for the most-recent deployment.

Note:

We added this return in cPanel & WHM version 74.

The function returns this value in the last_deployment hash.

A time, in Unix time format.1410277881

repository_state

hash

A hash of information about the state of the repository at the time of the most recent deployment.

Note:

We added this hash in cPanel & WHM version 74.

The function returns this hash in the last_deployment hash.

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

date

string

The timestamp for the commit that the system most recently deployed.

Note:

We added this return in cPanel & WHM version 74.

The function returns this value in the repository_state hash.

A time, in Unix time format.1410277881

identifier

string

The identifier (SHA-1 value) for the commit that the system most recently deployed.

Note:

We added this return in cPanel & WHM version 74.

The function returns this value in the repository_state hash.

A valid SHA-1 value.2fd4e1c67a2d28fced849ee1bb76e7391b93eb12

author

string

The author's name and email address for the commit that the system most recently deployed.

Note:

We added this return in cPanel & WHM version 74.

The function returns this value 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 for the commit that the system most recently deployed.

Note:

We added this return in cPanel & WHM version 74.

The function returns this value in the repository_state hash.

A valid string.I'm committing some particularly cromulent code.

clone_urls

hash of arrays

A hash of arrays of URLs to use to clone the repository.

The function returns this hash in the repository's hash.

This hash includes the read_write and read_only arrays. 

read_write

array

An array of clone URLs with read-write permissions.

The function returns this array in the clone_urls hash.

  • One or more valid URLs.
  • A blank array, if the account does not include the Shell Access setting.

Important:

If the server uses a nonstandard SSH port, the system returns a clone URL that includes the port number. 

ssh://user@example.com/home/user/example

read_only

array

An array of clone URLs with read-only permissions.

The function returns this array in the clone_urls hash.

  • One or more valid URLs.
  • A blank array, if the account does not include the Shell Access setting.

Important:

If the server uses a nonstandard SSH port, the system returns a clone URL that includes the port number. 

https://user@example.com/home/user/example

tasks

array of hashes

An array of hashes of information about the Task Queue system's process that will clone the repository.

Note:

The function only returns this value if the clone process is not finished.

The function returns this hash in the repository's hash.

This array of hashes includes the id , subsystem , and action returns.

id

string

The Task Queue system's task ID number.

The function returns this value in the tasks hash.

A valid process ID. 00000000/5a9ec8dd4c345d

subsystem

string

The Task Queue subsystem that will handle the task.

The function returns this value in the tasks hash.

VersionControl is the only possible value.VersionControl

action

string

The task's action.

The function returns this value in the tasks hash.

  • create — Create the repository.
  • deploy — Deploy the repository.
create

args

hash

A hash of arguments for the Task Queue system's process.

Note:

We added this return in cPanel & WHM version 74.

The function returns this value in the action hash.

This hash includes the repository_root and log_file returns.

repository_root

string

The repository's directory.

Note:

We added this return in cPanel & WHM version 74.

The function returns this value in the args hash.

A valid absolute path to a directory within the user's home directory. /home/user/example

log_file

string

The process's log file.

Notes:

  • The function only returns this value if the process generated a log file.
  • We added this return in cPanel & WHM version 74.

The function returns this value in the args hash.

A valid absolute path to a log file.
 Click to view...

/home/username/.cpanel/logs/vc_1234567890.123456_git_deploy.log