From f7749bbbef6f34e587513f1606f5f03c931afd36 Mon Sep 17 00:00:00 2001
From: Khushboo Verma <43381712+vermakhushboo@users.noreply.github.com>
Date: Wed, 19 Feb 2025 14:55:44 +0530
Subject: [PATCH 1/2] Add createVcsDeployment endpoints for sites and functions

---
 .../Functions/Http/Deployments/Vcs/Create.php | 89 +++++++++++++++++++
 .../Modules/Functions/Services/Http.php       |  2 +
 .../Http/Deployments/Template/Create.php      | 22 +----
 .../Sites/Http/Deployments/Vcs/Create.php     | 89 +++++++++++++++++++
 .../Platform/Modules/Sites/Services/Http.php  |  2 +
 5 files changed, 183 insertions(+), 21 deletions(-)
 create mode 100644 src/Appwrite/Platform/Modules/Functions/Http/Deployments/Vcs/Create.php
 create mode 100644 src/Appwrite/Platform/Modules/Sites/Http/Deployments/Vcs/Create.php

diff --git a/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Vcs/Create.php b/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Vcs/Create.php
new file mode 100644
index 0000000000..ad57741634
--- /dev/null
+++ b/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Vcs/Create.php
@@ -0,0 +1,89 @@
+<?php
+
+namespace Appwrite\Platform\Modules\Functions\Http\Deployments\Vcs;
+
+use Appwrite\Event\Build;
+use Appwrite\Event\Event;
+use Appwrite\Extend\Exception;
+use Appwrite\Platform\Modules\Compute\Base;
+use Appwrite\SDK\AuthType;
+use Appwrite\SDK\Method;
+use Appwrite\SDK\Response as SDKResponse;
+use Appwrite\Utopia\Response;
+use Utopia\Database\Database;
+use Utopia\Database\Document;
+use Utopia\Database\Validator\UID;
+use Utopia\Platform\Action;
+use Utopia\Platform\Scope\HTTP;
+use Utopia\Swoole\Request;
+use Utopia\VCS\Adapter\Git\GitHub;
+
+class Create extends Base
+{
+    use HTTP;
+
+    public static function getName()
+    {
+        return 'createVcsDeployment';
+    }
+
+    public function __construct()
+    {
+        $this
+            ->setHttpMethod(Action::HTTP_REQUEST_METHOD_POST)
+            ->setHttpPath('/v1/functions/:functionId/deployments/vcs')
+            ->desc('Create deployment')
+            ->groups(['api', 'functions'])
+            ->label('scope', 'functions.write')
+            ->label('event', 'functions.[functionId].deployments.[deploymentId].create')
+            ->label('audits.event', 'deployment.create')
+            ->label('audits.resource', 'function/{request.functionId}')
+            ->label('sdk', new Method(
+                namespace: 'functions',
+                name: 'createVcsDeployment',
+                description: <<<EOT
+                Create a deployment when a function is connected to VCS.
+                EOT,
+                auth: [AuthType::KEY],
+                responses: [
+                    new SDKResponse(
+                        code: Response::STATUS_CODE_ACCEPTED,
+                        model: Response::MODEL_DEPLOYMENT,
+                    )
+                ],
+            ))
+            ->param('functionId', '', new UID(), 'Function ID.')
+            ->inject('request')
+            ->inject('response')
+            ->inject('dbForProject')
+            ->inject('dbForPlatform')
+            ->inject('project')
+            ->inject('queueForEvents')
+            ->inject('queueForBuilds')
+            ->inject('gitHub')
+            ->callback([$this, 'action']);
+    }
+
+    public function action(string $functionId, Request $request, Response $response, Database $dbForProject, Database $dbForPlatform, Document $project, Event $queueForEvents, Build $queueForBuilds, GitHub $github)
+    {
+        $function = $dbForProject->getDocument('functions', $functionId);
+
+        if ($function->isEmpty()) {
+            throw new Exception(Exception::FUNCTION_NOT_FOUND);
+        }
+
+        $template = new Document();
+
+        $installation = $dbForPlatform->getDocument('installations', $function->getAttribute('installationId'));
+
+        $deployment = $this->redeployVcsFunction($request, $function, $project, $installation, $dbForProject, $queueForBuilds, $template, $github);
+
+        $queueForEvents
+            ->setParam('functionId', $function->getId())
+            ->setParam('deploymentId', $deployment->getId());
+
+        $response
+            ->setStatusCode(Response::STATUS_CODE_ACCEPTED)
+            ->dynamic($deployment, Response::MODEL_DEPLOYMENT);
+    }
+}
diff --git a/src/Appwrite/Platform/Modules/Functions/Services/Http.php b/src/Appwrite/Platform/Modules/Functions/Services/Http.php
index 141c4abb62..629817827c 100644
--- a/src/Appwrite/Platform/Modules/Functions/Services/Http.php
+++ b/src/Appwrite/Platform/Modules/Functions/Services/Http.php
@@ -4,6 +4,7 @@ namespace Appwrite\Platform\Modules\Functions\Services;
 
 use Appwrite\Platform\Modules\Functions\Http\Deployments\Create as CreateDeployment;
 use Appwrite\Platform\Modules\Functions\Http\Deployments\Template\Create as CreateTemplateDeployment;
+use Appwrite\Platform\Modules\Functions\Http\Deployments\Vcs\Create as CreateVcsDeployment;
 use Appwrite\Platform\Modules\Functions\Http\Functions\Create as CreateFunction;
 use Appwrite\Platform\Modules\Functions\Http\Functions\Update as UpdateFunction;
 use Appwrite\Platform\Modules\Functions\Http\Functions\XList as ListFunctions;
@@ -21,5 +22,6 @@ class Http extends Service
         $this->addAction(ListRuntimes::getName(), new ListRuntimes());
         $this->addAction(CreateDeployment::getName(), new CreateDeployment());
         $this->addAction(CreateTemplateDeployment::getName(), new CreateTemplateDeployment());
+        $this->addAction(CreateVcsDeployment::getName(), new CreateVcsDeployment());
     }
 }
diff --git a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Template/Create.php b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Template/Create.php
index 507397d70c..005b6369d8 100644
--- a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Template/Create.php
+++ b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Template/Create.php
@@ -19,11 +19,9 @@ use Utopia\Database\Validator\Authorization;
 use Utopia\Database\Validator\UID;
 use Utopia\Platform\Action;
 use Utopia\Platform\Scope\HTTP;
-use Utopia\Swoole\Request;
 use Utopia\System\System;
 use Utopia\Validator\Boolean;
 use Utopia\Validator\Text;
-use Utopia\VCS\Adapter\Git\GitHub;
 
 class Create extends Base
 {
@@ -67,18 +65,16 @@ class Create extends Base
             ->param('rootDirectory', '', new Text(128, 0), 'Path to site code in the template repo.')
             ->param('version', '', new Text(128, 0), 'Version (tag) for the repo linked to the site template.')
             ->param('activate', false, new Boolean(), 'Automatically activate the deployment when it is finished building.', true)
-            ->inject('request')
             ->inject('response')
             ->inject('dbForProject')
             ->inject('dbForPlatform')
             ->inject('project')
             ->inject('queueForEvents')
             ->inject('queueForBuilds')
-            ->inject('gitHub')
             ->callback([$this, 'action']);
     }
 
-    public function action(string $siteId, string $repository, string $owner, string $rootDirectory, string $version, bool $activate, Request $request, Response $response, Database $dbForProject, Database $dbForPlatform, Document $project, Event $queueForEvents, Build $queueForBuilds, GitHub $github)
+    public function action(string $siteId, string $repository, string $owner, string $rootDirectory, string $version, bool $activate, Response $response, Database $dbForProject, Database $dbForPlatform, Document $project, Event $queueForEvents, Build $queueForBuilds)
     {
         $site = $dbForProject->getDocument('sites', $siteId);
 
@@ -93,22 +89,6 @@ class Create extends Base
             'version' => $version
         ]);
 
-        if (!empty($providerRepositoryId)) {
-            $installation = $dbForPlatform->getDocument('installations', $site->getAttribute('installationId'));
-
-            $deployment = $this->redeployVcsSite($request, $site, $project, $installation, $dbForProject, $dbForPlatform, $queueForBuilds, $template, $github);
-
-            $queueForEvents
-                ->setParam('siteId', $site->getId())
-                ->setParam('deploymentId', $deployment->getId());
-
-            $response
-                ->setStatusCode(Response::STATUS_CODE_ACCEPTED)
-                ->dynamic($deployment, Response::MODEL_DEPLOYMENT);
-
-            return;
-        }
-
         $deploymentId = ID::unique();
         $deployment = $dbForProject->createDocument('deployments', new Document([
             '$id' => $deploymentId,
diff --git a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Vcs/Create.php b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Vcs/Create.php
new file mode 100644
index 0000000000..151b33bf53
--- /dev/null
+++ b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Vcs/Create.php
@@ -0,0 +1,89 @@
+<?php
+
+namespace Appwrite\Platform\Modules\Sites\Http\Deployments\Vcs;
+
+use Appwrite\Event\Build;
+use Appwrite\Event\Event;
+use Appwrite\Extend\Exception;
+use Appwrite\Platform\Modules\Compute\Base;
+use Appwrite\SDK\AuthType;
+use Appwrite\SDK\Method;
+use Appwrite\SDK\Response as SDKResponse;
+use Appwrite\Utopia\Response;
+use Utopia\Database\Database;
+use Utopia\Database\Document;
+use Utopia\Database\Validator\UID;
+use Utopia\Platform\Action;
+use Utopia\Platform\Scope\HTTP;
+use Utopia\Swoole\Request;
+use Utopia\VCS\Adapter\Git\GitHub;
+
+class Create extends Base
+{
+    use HTTP;
+
+    public static function getName()
+    {
+        return 'createVcsDeployment';
+    }
+
+    public function __construct()
+    {
+        $this
+            ->setHttpMethod(Action::HTTP_REQUEST_METHOD_POST)
+            ->setHttpPath('/v1/sites/:siteId/deployments/vcs')
+            ->desc('Create deployment')
+            ->groups(['api', 'sites'])
+            ->label('scope', 'sites.write')
+            ->label('event', 'sites.[siteId].deployments.[deploymentId].create')
+            ->label('audits.event', 'deployment.create')
+            ->label('audits.resource', 'site/{request.siteId}')
+            ->label('sdk', new Method(
+                namespace: 'sites',
+                name: 'createVcsDeployment',
+                description: <<<EOT
+                Create a deployment when a site is connected to VCS.
+                EOT,
+                auth: [AuthType::KEY],
+                responses: [
+                    new SDKResponse(
+                        code: Response::STATUS_CODE_ACCEPTED,
+                        model: Response::MODEL_DEPLOYMENT,
+                    )
+                ],
+            ))
+            ->param('siteId', '', new UID(), 'Site ID.')
+            ->inject('request')
+            ->inject('response')
+            ->inject('dbForProject')
+            ->inject('dbForPlatform')
+            ->inject('project')
+            ->inject('queueForEvents')
+            ->inject('queueForBuilds')
+            ->inject('gitHub')
+            ->callback([$this, 'action']);
+    }
+
+    public function action(string $siteId, Request $request, Response $response, Database $dbForProject, Database $dbForPlatform, Document $project, Event $queueForEvents, Build $queueForBuilds, GitHub $github)
+    {
+        $site = $dbForProject->getDocument('sites', $siteId);
+
+        if ($site->isEmpty()) {
+            throw new Exception(Exception::SITE_NOT_FOUND);
+        }
+
+        $template = new Document();
+
+        $installation = $dbForPlatform->getDocument('installations', $site->getAttribute('installationId'));
+
+        $deployment = $this->redeployVcsSite($request, $site, $project, $installation, $dbForProject, $dbForPlatform, $queueForBuilds, $template, $github);
+
+        $queueForEvents
+            ->setParam('siteId', $site->getId())
+            ->setParam('deploymentId', $deployment->getId());
+
+        $response
+            ->setStatusCode(Response::STATUS_CODE_ACCEPTED)
+            ->dynamic($deployment, Response::MODEL_DEPLOYMENT);
+    }
+}
diff --git a/src/Appwrite/Platform/Modules/Sites/Services/Http.php b/src/Appwrite/Platform/Modules/Sites/Services/Http.php
index b43919acb7..9df4329b01 100644
--- a/src/Appwrite/Platform/Modules/Sites/Services/Http.php
+++ b/src/Appwrite/Platform/Modules/Sites/Services/Http.php
@@ -11,6 +11,7 @@ use Appwrite\Platform\Modules\Sites\Http\Deployments\Download\Get as DownloadDep
 use Appwrite\Platform\Modules\Sites\Http\Deployments\Get as GetDeployment;
 use Appwrite\Platform\Modules\Sites\Http\Deployments\Template\Create as CreateTemplateDeployment;
 use Appwrite\Platform\Modules\Sites\Http\Deployments\Update as UpdateDeployment;
+use Appwrite\Platform\Modules\Sites\Http\Deployments\Vcs\Create as CreateVcsDeployment;
 use Appwrite\Platform\Modules\Sites\Http\Deployments\XList as ListDeployments;
 use Appwrite\Platform\Modules\Sites\Http\Frameworks\XList as ListFrameworks;
 use Appwrite\Platform\Modules\Sites\Http\Logs\Delete as DeleteLog;
@@ -51,6 +52,7 @@ class Http extends Service
         // Deployments
         $this->addAction(CreateDeployment::getName(), new CreateDeployment());
         $this->addAction(CreateTemplateDeployment::getName(), new CreateTemplateDeployment());
+        $this->addAction(CreateVcsDeployment::getName(), new CreateVcsDeployment());
         $this->addAction(GetDeployment::getName(), new GetDeployment());
         $this->addAction(ListDeployments::getName(), new ListDeployments());
         $this->addAction(UpdateDeployment::getName(), new UpdateDeployment());

From 63a91e30fa9f3833c7ee23a50223f43bd4232d57 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Matej=20Ba=C4=8Do?= <matejbaco2000@gmail.com>
Date: Wed, 19 Feb 2025 11:50:25 +0100
Subject: [PATCH 2/2] Add reference params

---
 .../Platform/Modules/Compute/Base.php         | 17 ++++++++++---
 .../Functions/Http/Deployments/Vcs/Create.php | 24 +++++++++++++++---
 .../Http/Deployments/Template/Create.php      | 22 +++++++++++++++-
 .../Sites/Http/Deployments/Vcs/Create.php     | 25 ++++++++++++++++---
 4 files changed, 77 insertions(+), 11 deletions(-)

diff --git a/src/Appwrite/Platform/Modules/Compute/Base.php b/src/Appwrite/Platform/Modules/Compute/Base.php
index 1c3b9f2ede..e8f8ab764d 100644
--- a/src/Appwrite/Platform/Modules/Compute/Base.php
+++ b/src/Appwrite/Platform/Modules/Compute/Base.php
@@ -19,7 +19,7 @@ use Utopia\VCS\Exception\RepositoryNotFound;
 
 class Base extends Action
 {
-    public function redeployVcsFunction(Request $request, Document $function, Document $project, Document $installation, Database $dbForProject, Build $queueForBuilds, Document $template, GitHub $github): Document
+    public function redeployVcsFunction(Request $request, Document $function, Document $project, Document $installation, Database $dbForProject, Build $queueForBuilds, Document $template, GitHub $github, string $referenceType = 'branch', string $reference = ''): Document
     {
         $deploymentId = ID::unique();
         $entrypoint = $function->getAttribute('entrypoint', '');
@@ -37,7 +37,12 @@ class Base extends Action
         } catch (RepositoryNotFound $e) {
             throw new Exception(Exception::PROVIDER_REPOSITORY_NOT_FOUND);
         }
-        $providerBranch = $function->getAttribute('providerBranch', 'main');
+
+        // TODO: Support tag and commit in future
+        if ($referenceType === 'branch') {
+            $providerBranch = empty($reference) ? $function->getAttribute('providerBranch', 'main') : $reference;
+        }
+
         $authorUrl = "https://github.com/$owner";
         $repositoryUrl = "https://github.com/$owner/$repositoryName";
         $branchUrl = "https://github.com/$owner/$repositoryName/tree/$providerBranch";
@@ -95,7 +100,7 @@ class Base extends Action
         return $deployment;
     }
 
-    public function redeployVcsSite(Request $request, Document $site, Document $project, Document $installation, Database $dbForProject, Database $dbForPlatform, Build $queueForBuilds, Document $template, GitHub $github): Document
+    public function redeployVcsSite(Request $request, Document $site, Document $project, Document $installation, Database $dbForProject, Database $dbForPlatform, Build $queueForBuilds, Document $template, GitHub $github, string $referenceType = 'branch', string $reference = ''): Document
     {
         $deploymentId = ID::unique();
         $providerInstallationId = $installation->getAttribute('providerInstallationId', '');
@@ -113,7 +118,11 @@ class Base extends Action
             throw new Exception(Exception::PROVIDER_REPOSITORY_NOT_FOUND);
         }
 
-        $providerBranch = $site->getAttribute('providerBranch', 'main');
+        // TODO: Support tag and commit in future
+        if ($referenceType === 'branch') {
+            $providerBranch = empty($reference) ? $site->getAttribute('providerBranch', 'main') : $reference;
+        }
+
         $authorUrl = "https://github.com/$owner";
         $repositoryUrl = "https://github.com/$owner/$repositoryName";
         $branchUrl = "https://github.com/$owner/$repositoryName/tree/$providerBranch";
diff --git a/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Vcs/Create.php b/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Vcs/Create.php
index ad57741634..6efa86a2f5 100644
--- a/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Vcs/Create.php
+++ b/src/Appwrite/Platform/Modules/Functions/Http/Deployments/Vcs/Create.php
@@ -16,6 +16,8 @@ use Utopia\Database\Validator\UID;
 use Utopia\Platform\Action;
 use Utopia\Platform\Scope\HTTP;
 use Utopia\Swoole\Request;
+use Utopia\Validator\Text;
+use Utopia\Validator\WhiteList;
 use Utopia\VCS\Adapter\Git\GitHub;
 
 class Create extends Base
@@ -32,7 +34,7 @@ class Create extends Base
         $this
             ->setHttpMethod(Action::HTTP_REQUEST_METHOD_POST)
             ->setHttpPath('/v1/functions/:functionId/deployments/vcs')
-            ->desc('Create deployment')
+            ->desc('Create VCS deployment')
             ->groups(['api', 'functions'])
             ->label('scope', 'functions.write')
             ->label('event', 'functions.[functionId].deployments.[deploymentId].create')
@@ -43,6 +45,8 @@ class Create extends Base
                 name: 'createVcsDeployment',
                 description: <<<EOT
                 Create a deployment when a function is connected to VCS.
+
+                This endpoint lets you create deployment from a branch, commit, or a tag.
                 EOT,
                 auth: [AuthType::KEY],
                 responses: [
@@ -53,6 +57,9 @@ class Create extends Base
                 ],
             ))
             ->param('functionId', '', new UID(), 'Function ID.')
+            // TODO: Support tag and commit in future
+            ->param('type', '', new WhiteList(['branch']), 'Type of reference passed. Allowed values are: branch')
+            ->param('reference', '', new Text(255), 'VCS reference to create deployment from. Depending on type this can be: branch name')
             ->inject('request')
             ->inject('response')
             ->inject('dbForProject')
@@ -64,7 +71,7 @@ class Create extends Base
             ->callback([$this, 'action']);
     }
 
-    public function action(string $functionId, Request $request, Response $response, Database $dbForProject, Database $dbForPlatform, Document $project, Event $queueForEvents, Build $queueForBuilds, GitHub $github)
+    public function action(string $functionId, string $type, string $reference, Request $request, Response $response, Database $dbForProject, Database $dbForPlatform, Document $project, Event $queueForEvents, Build $queueForBuilds, GitHub $github)
     {
         $function = $dbForProject->getDocument('functions', $functionId);
 
@@ -76,7 +83,18 @@ class Create extends Base
 
         $installation = $dbForPlatform->getDocument('installations', $function->getAttribute('installationId'));
 
-        $deployment = $this->redeployVcsFunction($request, $function, $project, $installation, $dbForProject, $queueForBuilds, $template, $github);
+        $deployment = $this->redeployVcsFunction(
+            request: $request,
+            function: $function,
+            project: $project,
+            installation: $installation,
+            dbForProject: $dbForProject,
+            queueForBuilds: $queueForBuilds,
+            template: $template,
+            github: $github,
+            reference: $reference,
+            referenceType: $type
+        );
 
         $queueForEvents
             ->setParam('functionId', $function->getId())
diff --git a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Template/Create.php b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Template/Create.php
index 005b6369d8..e1658d2493 100644
--- a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Template/Create.php
+++ b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Template/Create.php
@@ -19,9 +19,11 @@ use Utopia\Database\Validator\Authorization;
 use Utopia\Database\Validator\UID;
 use Utopia\Platform\Action;
 use Utopia\Platform\Scope\HTTP;
+use Utopia\Swoole\Request;
 use Utopia\System\System;
 use Utopia\Validator\Boolean;
 use Utopia\Validator\Text;
+use Utopia\VCS\Adapter\Git\GitHub;
 
 class Create extends Base
 {
@@ -65,16 +67,18 @@ class Create extends Base
             ->param('rootDirectory', '', new Text(128, 0), 'Path to site code in the template repo.')
             ->param('version', '', new Text(128, 0), 'Version (tag) for the repo linked to the site template.')
             ->param('activate', false, new Boolean(), 'Automatically activate the deployment when it is finished building.', true)
+            ->inject('request')
             ->inject('response')
             ->inject('dbForProject')
             ->inject('dbForPlatform')
             ->inject('project')
             ->inject('queueForEvents')
             ->inject('queueForBuilds')
+            ->inject('gitHub')
             ->callback([$this, 'action']);
     }
 
-    public function action(string $siteId, string $repository, string $owner, string $rootDirectory, string $version, bool $activate, Response $response, Database $dbForProject, Database $dbForPlatform, Document $project, Event $queueForEvents, Build $queueForBuilds)
+    public function action(string $siteId, string $repository, string $owner, string $rootDirectory, string $version, bool $activate, Request $request, Response $response, Database $dbForProject, Database $dbForPlatform, Document $project, Event $queueForEvents, Build $queueForBuilds, GitHub $github)
     {
         $site = $dbForProject->getDocument('sites', $siteId);
 
@@ -89,6 +93,22 @@ class Create extends Base
             'version' => $version
         ]);
 
+        if (!empty($site->getAttribute('providerRepositoryId'))) {
+            $installation = $dbForPlatform->getDocument('installations', $site->getAttribute('installationId'));
+
+            $deployment = $this->redeployVcsSite($request, $site, $project, $installation, $dbForProject, $dbForPlatform, $queueForBuilds, $template, $github);
+
+            $queueForEvents
+            ->setParam('siteId', $site->getId())
+            ->setParam('deploymentId', $deployment->getId());
+
+            $response
+                ->setStatusCode(Response::STATUS_CODE_ACCEPTED)
+                ->dynamic($deployment, Response::MODEL_DEPLOYMENT);
+
+            return;
+        }
+
         $deploymentId = ID::unique();
         $deployment = $dbForProject->createDocument('deployments', new Document([
             '$id' => $deploymentId,
diff --git a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Vcs/Create.php b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Vcs/Create.php
index 151b33bf53..03590c6a7d 100644
--- a/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Vcs/Create.php
+++ b/src/Appwrite/Platform/Modules/Sites/Http/Deployments/Vcs/Create.php
@@ -16,6 +16,8 @@ use Utopia\Database\Validator\UID;
 use Utopia\Platform\Action;
 use Utopia\Platform\Scope\HTTP;
 use Utopia\Swoole\Request;
+use Utopia\Validator\Text;
+use Utopia\Validator\WhiteList;
 use Utopia\VCS\Adapter\Git\GitHub;
 
 class Create extends Base
@@ -32,7 +34,7 @@ class Create extends Base
         $this
             ->setHttpMethod(Action::HTTP_REQUEST_METHOD_POST)
             ->setHttpPath('/v1/sites/:siteId/deployments/vcs')
-            ->desc('Create deployment')
+            ->desc('Create VCS deployment')
             ->groups(['api', 'sites'])
             ->label('scope', 'sites.write')
             ->label('event', 'sites.[siteId].deployments.[deploymentId].create')
@@ -43,6 +45,8 @@ class Create extends Base
                 name: 'createVcsDeployment',
                 description: <<<EOT
                 Create a deployment when a site is connected to VCS.
+
+                This endpoint lets you create deployment from a branch, commit, or a tag.
                 EOT,
                 auth: [AuthType::KEY],
                 responses: [
@@ -53,6 +57,9 @@ class Create extends Base
                 ],
             ))
             ->param('siteId', '', new UID(), 'Site ID.')
+            // TODO: Support tag and commit in future
+            ->param('type', '', new WhiteList(['branch']), 'Type of reference passed. Allowed values are: branch')
+            ->param('reference', '', new Text(255), 'VCS reference to create deployment from. Depending on type this can be: branch name')
             ->inject('request')
             ->inject('response')
             ->inject('dbForProject')
@@ -64,7 +71,7 @@ class Create extends Base
             ->callback([$this, 'action']);
     }
 
-    public function action(string $siteId, Request $request, Response $response, Database $dbForProject, Database $dbForPlatform, Document $project, Event $queueForEvents, Build $queueForBuilds, GitHub $github)
+    public function action(string $siteId, string $type, string $reference, Request $request, Response $response, Database $dbForProject, Database $dbForPlatform, Document $project, Event $queueForEvents, Build $queueForBuilds, GitHub $github)
     {
         $site = $dbForProject->getDocument('sites', $siteId);
 
@@ -76,7 +83,19 @@ class Create extends Base
 
         $installation = $dbForPlatform->getDocument('installations', $site->getAttribute('installationId'));
 
-        $deployment = $this->redeployVcsSite($request, $site, $project, $installation, $dbForProject, $dbForPlatform, $queueForBuilds, $template, $github);
+        $deployment = $this->redeployVcsSite(
+            request: $request,
+            site: $site,
+            project: $project,
+            installation: $installation,
+            dbForProject: $dbForProject,
+            dbForPlatform: $dbForPlatform,
+            queueForBuilds: $queueForBuilds,
+            template: $template,
+            github: $github,
+            reference: $reference,
+            referenceType: $type
+        );
 
         $queueForEvents
             ->setParam('siteId', $site->getId())