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

Description

This function creates a new Git™ repository on a cPanel account.

Important:

The system logs errors for this function in the ~/.cpanel/logs/vc_TIMESTAMP_git_create.log file, where TIMESTAMP represents the time of the error in Unix epoch time.


Examples  


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/VersionControl/create?type=git&name=example&repository_root=%2Fhome%2Fuser%2Fexample&source_repository%3D%27%7B%22remote_name%22%3A%22origin%22%2C%22url%22%3A%22ssh%3A%2F%2Fuser%40example.com%2Fhome%2Fuser%2Fexample%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.
 
// Create a new repository.
$source_repositoryObj -> remote_name = "origin";
$source_repositoryObj -> url = "ssh://user@example.com/home/user/example";
$create = $cpanel->uapi(
    'VersionControl', 'create',
     array(
        'type'               => 'git',
        'name'               => 'example',
        'repository_root'    => '/home/user/example',
        '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.
 
# Create a new repository.
my $create = $cpliveapi->uapi(
    'VersionControl', 'create',    {
        'type'               => 'git',
        'name'               => 'example',
        'repository_root'    => '/home/user/example',
        'source_repository'  => {
           "remote_name" => "origin", 
           "url" => "ssh://user@example.com/home/user/example" 
        },
   }
);


Note:

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

 

 cPanel Template Toolkit
<!-- Create a new repository. -->
[% data = execute( 
   'VersionControl', 'create', {
        'type'               => 'git',
        'name'               => 'example',
        'repository_root'    => '/home/user/example',
        'source_repository'  => {
           "remote_name" : "origin", 
           "url" : "ssh://user@example.com/home/user/example" 
        },
   } 
); %]


Note:

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

 

 Command Line
uapi --user=username VersionControl create type=git name=example repository_root=/home/user/example source_repository='{"remote_name":"origin","url":"ssh://user@example.com/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/api/uapi


 Output (JSON)
{  
   "errors":null,
   "data":{  
      "name":"example",
      "type":"git",
      "repository_root":"/home/user/example",
      "branch":"master",
      "source_repository":{  
         "remote_name":"remote",
         "url":"http://user@domain.com/home/user/domain",
      },
      "available_branches":[  
         "master",
         "olive",
      ],
      "clone_urls":{  
         "read_only":[  
            "https://user@example.com/home/user/example"
         ],
         "read_write":[  
            "ssh://user@example.com/home/user/example",
         ]
      },
      "tasks": [
          {  
              "id": "00000000/5a9ec8dd4c345d",
              "subsystem": "VersionControl",
              "action": "create"
              "sse_url": "/sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0",
              "args": {
                  "repository_root": "/home/user/public_html/howdy",
                  "log_file": "/home/user/.cpanel/logs/vc_1526305129.123456_git_create.log"
            }
          }
      ]
   },
   "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

type

string

Required

The repository type.

git is the only possible value.git
namestring

Required

The new repository's display name.

A valid string.example
repository_rootstring

Required

The directory in which to store the repository.

 

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

Notes:

  • If the directory does not exist, the system will create it.
  • If the specified directory already contains a repository, the system will automatically add it to the list of cPanel-managed repositories.
  • This feature enforces several restrictions on repository paths. For more information, read our Guide to Git - For System Administrators documentation.

/home/user/public_html/example

 

source_repositoryhash

A hash of information about the source repository that the system will clone.

Note:

If you do not include source repository data, the function creates an empty repository. 

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.

This parameter defaults to origin.

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.

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

 

Returns

ReturnTypeDescriptionPossible valuesExample

type

string

The repository type.

git is the only possible value.git

name

string

The repository's display name.

A valid string.

example

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, or no local branches exist.
master

 

source_repositoryhash

A hash of information about a cloned repository's source repository.

Note:

The function only returns this hash if it will clone a repository.

This hash includes the remote_name and url returns.

remote_name

string

The source repository's name.

The function returns this value in the source_repository hash.

A valid string.remote

url

string

The source repository's clone URL.

The function returns this value in the source_repository hash.

A valid clone URL. http://user@domain.com/home/user/domain

available_branches

array of strings

An array of available branches for the repository.

  • An array of branch names that exist for the cloned or existing repository.
  • An empty array.
master

last_update

string

Information about the most-recent (HEAD) commit for the current branch.

Note:

The system may require a large amount of time to clone larger repositories. Until this process finishes, HEAD information is unavailable.

null is the only possible value.

null

clone_urls

hash of arrays

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

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 it will clone a repository.

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 task 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 is the only possible value.create

sse_url

string

The SSE interface to track the progress of the process.

Note:

We added this return in cPanel & WHM version 74.

The function returns this value in the tasks hash.

A valid SSE URL. /sse/UserTasks/B3A27B96-51F7-11E8-92E3-CC90C4F823F0

args

hash

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

The function returns this hash in the tasks hash.

This hash includes the repository_root and log_file returns.

repository_root

string

The repository's directory.

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. /home/username/.cpanel/logs/vc_1234567890.123456_git_deploy.log