From 696b266fc50e394a9d2d26b15a910787238ae6ec Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 04:31:31 +0000 Subject: [PATCH 1/9] fix(projects): mark deployment onboarding stages from the build lifecycle The deployment onboarding stages (functions.createDeployment, functions.updateFunctionDeployment, sites.createDeployment, sites.updateSiteDeployment) never marked on a normal deploy because the shutdown hook keys onboarding off the request's SDK method: - deployments are created via several paths (manual upload, template, duplicate, and VCS webhooks) whose SDK methods differ from createDeployment, and VCS creates the deployment server-side with no labelled request; - activation is performed by the builds worker via the activate flag, not the updateFunctionDeployment/updateSiteDeployment routes, so those stages were effectively unreachable. Mark these stages at the build-lifecycle choke point instead, where every creation path and the worker-driven activation converge. Extract the read-modify-write into a reusable Appwrite\Onboarding\Onboarding helper that persists multiple stages in a single update (so create + activate cannot clobber each other), and have the API shutdown hook reuse it. The builds worker writes onboarding via dbForPlatform - the same platform (console) database it already updates for the rules collection during activation - so the write reaches the central console store. --- app/controllers/shared/api.php | 25 +----- app/init/constants.php | 1 + src/Appwrite/Onboarding/Onboarding.php | 70 +++++++++++++++ .../Modules/Functions/Workers/Builds.php | 19 ++++ tests/unit/Onboarding/OnboardingTest.php | 89 +++++++++++++++++++ 5 files changed, 181 insertions(+), 23 deletions(-) create mode 100644 src/Appwrite/Onboarding/Onboarding.php create mode 100644 tests/unit/Onboarding/OnboardingTest.php diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index e30305e55b..6f040fc4b5 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -16,6 +16,7 @@ use Appwrite\Event\Webhook; use Appwrite\Extend\Exception; use Appwrite\Extend\Exception as AppwriteException; use Appwrite\Functions\EventProcessor; +use Appwrite\Onboarding\Onboarding; use Appwrite\Platform\Modules\Storage\Config\CacheControl; use Appwrite\Platform\Modules\Storage\Config\StorageCacheControl; use Appwrite\SDK\Method; @@ -23,7 +24,6 @@ use Appwrite\Usage\Context; use Appwrite\Utopia\Database\Documents\User; use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; -use Throwable; use Utopia\Abuse\Abuse; use Utopia\Bus\Bus; use Utopia\Cache\Adapter\Filesystem; @@ -1167,16 +1167,6 @@ Http::shutdown() return; } - $byMethod = $project->getAttribute('onboarding', []); - $status = \is_array($byMethod) ? ($byMethod[$method]['status'] ?? null) : null; - if ($status === ONBOARDING_STATUS_COMPLETED || $status === ONBOARDING_STATUS_SKIPPED) { - return; - } - - if (! \is_array($byMethod)) { - $byMethod = []; - } - $actorType = ($apiKey !== null && $apiKey->getRole() === User::ROLE_KEYS) ? match ($apiKey->getType()) { API_KEY_ACCOUNT => ACTOR_TYPE_KEY_ACCOUNT, @@ -1187,19 +1177,8 @@ Http::shutdown() : (! $user->isEmpty() ? ($mode === APP_MODE_ADMIN ? ACTOR_TYPE_ADMIN : ACTOR_TYPE_USER) : ACTOR_TYPE_GUEST); - $byMethod[$method] = [ - 'status' => ONBOARDING_STATUS_COMPLETED, - 'at' => DateTime::now(), - 'actorType' => $actorType, - ]; - try { - $authorization->skip(fn () => $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'onboarding' => $byMethod, - ]))); - } catch (Throwable) { - // Missing `onboarding` attribute on upgraded installs must not break the request lifecycle. - } + $authorization->skip(fn () => Onboarding::complete($dbForPlatform, $project, [$method], $actorType)); }); Http::init() diff --git a/app/init/constants.php b/app/init/constants.php index 9efb6e3222..62819d601b 100644 --- a/app/init/constants.php +++ b/app/init/constants.php @@ -171,6 +171,7 @@ const ACTOR_TYPE_GUEST = 'guest'; const ACTOR_TYPE_KEY_PROJECT = 'keyProject'; const ACTOR_TYPE_KEY_ACCOUNT = 'keyAccount'; const ACTOR_TYPE_KEY_ORGANIZATION = 'keyOrganization'; +const ACTOR_TYPE_SYSTEM = 'system'; /** * Project onboarding stage status (stored per SDK method key under project.onboarding JSON). diff --git a/src/Appwrite/Onboarding/Onboarding.php b/src/Appwrite/Onboarding/Onboarding.php new file mode 100644 index 0000000000..555c3a10be --- /dev/null +++ b/src/Appwrite/Onboarding/Onboarding.php @@ -0,0 +1,70 @@ + $methods + */ + public static function complete(Database $dbForPlatform, Document $project, array $methods, string $actorType): void + { + if ($project->getId() === 'console' || $methods === []) { + return; + } + + $onboarding = Config::getParam('onboarding', []); + + $byMethod = $project->getAttribute('onboarding', []); + if (! \is_array($byMethod)) { + $byMethod = []; + } + + $changed = false; + foreach ($methods as $method) { + if (! isset($onboarding[$method])) { + continue; + } + + $status = $byMethod[$method]['status'] ?? null; + if ($status === ONBOARDING_STATUS_COMPLETED || $status === ONBOARDING_STATUS_SKIPPED) { + continue; + } + + $byMethod[$method] = [ + 'status' => ONBOARDING_STATUS_COMPLETED, + 'at' => DateTime::now(), + 'actorType' => $actorType, + ]; + $changed = true; + } + + if (! $changed) { + return; + } + + try { + $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ + 'onboarding' => $byMethod, + ])); + } catch (Throwable) { + // Missing `onboarding` attribute on upgraded installs must not break the caller. + } + } +} diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index d0806ccadf..2128dd610a 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -13,6 +13,7 @@ use Appwrite\Event\Realtime; use Appwrite\Event\Webhook; use Appwrite\Extend\Exception as AppwriteException; use Appwrite\Filter\BranchDomain as BranchDomainFilter; +use Appwrite\Onboarding\Onboarding; use Appwrite\Usage\Context; use Appwrite\Utopia\Response\Model\Deployment; use Appwrite\Vcs\Comment; @@ -1039,6 +1040,24 @@ class Builds extends Action Span::add('build.activated', true); } + /** + * Mark deployment onboarding stages. Done here (not via the HTTP sdk + * label) so every creation path - manual upload, template, duplicate + * and VCS - and the worker-driven activation are all covered. + */ + $onboardingMethods = match ($resource->getCollection()) { + 'functions' => ['create' => 'functions.createDeployment', 'activate' => 'functions.updateFunctionDeployment'], + 'sites' => ['create' => 'sites.createDeployment', 'activate' => 'sites.updateSiteDeployment'], + default => null, + }; + if ($onboardingMethods !== null) { + $stages = [$onboardingMethods['create']]; + if ($activateBuild) { + $stages[] = $onboardingMethods['activate']; + } + Onboarding::complete($dbForPlatform, $project, $stages, ACTOR_TYPE_SYSTEM); + } + $resource = $this->updateLatestDeployment($dbForProject, $resource); $this->afterDeploymentSuccess( diff --git a/tests/unit/Onboarding/OnboardingTest.php b/tests/unit/Onboarding/OnboardingTest.php new file mode 100644 index 0000000000..97ac84e9e0 --- /dev/null +++ b/tests/unit/Onboarding/OnboardingTest.php @@ -0,0 +1,89 @@ + true, + 'functions.updateFunctionDeployment' => true, + 'sites.createDeployment' => true, + ]); + } + + public function testCompletesMultipleStagesInASingleWrite(): void + { + $project = new Document(['$id' => 'project1', 'onboarding' => []]); + + $dbForPlatform = $this->createMock(Database::class); + $dbForPlatform->expects($this->once()) + ->method('updateDocument') + ->with( + 'projects', + 'project1', + $this->callback(function (Document $document): bool { + $onboarding = $document->getAttribute('onboarding'); + + return isset($onboarding['functions.createDeployment'], $onboarding['functions.updateFunctionDeployment']) + && $onboarding['functions.createDeployment']['status'] === ONBOARDING_STATUS_COMPLETED + && $onboarding['functions.createDeployment']['actorType'] === ACTOR_TYPE_SYSTEM + && ! empty($onboarding['functions.createDeployment']['at']); + }) + ); + + Onboarding::complete($dbForPlatform, $project, [ + 'functions.createDeployment', + 'functions.updateFunctionDeployment', + ], ACTOR_TYPE_SYSTEM); + } + + public function testIgnoresConsoleProject(): void + { + $project = new Document(['$id' => 'console', 'onboarding' => []]); + + $dbForPlatform = $this->createMock(Database::class); + $dbForPlatform->expects($this->never())->method('updateDocument'); + + Onboarding::complete($dbForPlatform, $project, ['functions.createDeployment'], ACTOR_TYPE_SYSTEM); + } + + public function testIgnoresUnknownAndAlreadyCompletedMethods(): void + { + $project = new Document(['$id' => 'project1', 'onboarding' => [ + 'functions.createDeployment' => [ + 'status' => ONBOARDING_STATUS_COMPLETED, + 'at' => '2026-01-01 00:00:00.000', + 'actorType' => ACTOR_TYPE_USER, + ], + ]]); + + $dbForPlatform = $this->createMock(Database::class); + $dbForPlatform->expects($this->never())->method('updateDocument'); + + Onboarding::complete($dbForPlatform, $project, ['functions.createDeployment', 'unknown.method'], ACTOR_TYPE_SYSTEM); + } + + public function testDoesNotOverwriteSkippedStage(): void + { + $project = new Document(['$id' => 'project1', 'onboarding' => [ + 'sites.createDeployment' => [ + 'status' => ONBOARDING_STATUS_SKIPPED, + 'at' => '2026-01-01 00:00:00.000', + 'actorType' => ACTOR_TYPE_USER, + ], + ]]); + + $dbForPlatform = $this->createMock(Database::class); + $dbForPlatform->expects($this->never())->method('updateDocument'); + + Onboarding::complete($dbForPlatform, $project, ['sites.createDeployment'], ACTOR_TYPE_SYSTEM); + } +} From 6d52a695a22db66f742d4e4f52a039e104860b69 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 04:44:23 +0000 Subject: [PATCH 2/9] feat(projects): per-type deployment onboarding stages Replace the single createDeployment stage with one key per deployment type (manual, cli, vcs) for functions and sites, keyed off the deployment `type` attribute. Every creation path maps to a type - manual upload -> manual, CLI -> cli, template + VCS/GitHub -> vcs - and the build worker marks the matching stage. Activation still marks updateFunctionDeployment/updateSiteDeployment. The UI can OR the per-type stages for a single "created a deployment" milestone while still tracking which deployment methods a project has used. --- app/config/onboarding.php | 12 +++++- .../Modules/Functions/Workers/Builds.php | 42 ++++++++++++++----- tests/unit/Onboarding/OnboardingTest.php | 26 ++++++------ 3 files changed, 56 insertions(+), 24 deletions(-) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 38f2bb8ec5..5b73328e25 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -40,7 +40,11 @@ return [ // Functions 'functions.create' => true, - 'functions.createDeployment' => true, + // One key per deployment creation type (deployment `type` attribute); + // OR them in the UI for a single "created a deployment" milestone. + 'functions.createManualDeployment' => true, + 'functions.createCliDeployment' => true, + 'functions.createVcsDeployment' => true, 'functions.updateFunctionDeployment' => true, // Messaging @@ -63,6 +67,10 @@ return [ // Sites 'sites.create' => true, - 'sites.createDeployment' => true, + // One key per deployment creation type (deployment `type` attribute); + // OR them in the UI for a single "created a deployment" milestone. + 'sites.createManualDeployment' => true, + 'sites.createCliDeployment' => true, + 'sites.createVcsDeployment' => true, 'sites.updateSiteDeployment' => true, ]; diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 2128dd610a..35ae9948d8 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -1042,19 +1042,41 @@ class Builds extends Action /** * Mark deployment onboarding stages. Done here (not via the HTTP sdk - * label) so every creation path - manual upload, template, duplicate - * and VCS - and the worker-driven activation are all covered. + * label) so every creation path - manual upload, CLI, template, + * duplicate and VCS - and the worker-driven activation are covered. + * The create stage is keyed by the deployment `type` so each type + * has its own stage (OR them in the UI for a single milestone). */ - $onboardingMethods = match ($resource->getCollection()) { - 'functions' => ['create' => 'functions.createDeployment', 'activate' => 'functions.updateFunctionDeployment'], - 'sites' => ['create' => 'sites.createDeployment', 'activate' => 'sites.updateSiteDeployment'], + $collection = $resource->getCollection(); + $createStage = match ($collection) { + 'functions' => match ($deployment->getAttribute('type')) { + 'manual' => 'functions.createManualDeployment', + 'cli' => 'functions.createCliDeployment', + 'vcs' => 'functions.createVcsDeployment', + default => null, + }, + 'sites' => match ($deployment->getAttribute('type')) { + 'manual' => 'sites.createManualDeployment', + 'cli' => 'sites.createCliDeployment', + 'vcs' => 'sites.createVcsDeployment', + default => null, + }, default => null, }; - if ($onboardingMethods !== null) { - $stages = [$onboardingMethods['create']]; - if ($activateBuild) { - $stages[] = $onboardingMethods['activate']; - } + $activateStage = match ($collection) { + 'functions' => 'functions.updateFunctionDeployment', + 'sites' => 'sites.updateSiteDeployment', + default => null, + }; + + $stages = []; + if ($createStage !== null) { + $stages[] = $createStage; + } + if ($activateBuild && $activateStage !== null) { + $stages[] = $activateStage; + } + if ($stages !== []) { Onboarding::complete($dbForPlatform, $project, $stages, ACTOR_TYPE_SYSTEM); } diff --git a/tests/unit/Onboarding/OnboardingTest.php b/tests/unit/Onboarding/OnboardingTest.php index 97ac84e9e0..2ce7d2635d 100644 --- a/tests/unit/Onboarding/OnboardingTest.php +++ b/tests/unit/Onboarding/OnboardingTest.php @@ -13,9 +13,11 @@ final class OnboardingTest extends TestCase protected function setUp(): void { Config::setParam('onboarding', [ - 'functions.createDeployment' => true, + 'functions.createManualDeployment' => true, + 'functions.createCliDeployment' => true, + 'functions.createVcsDeployment' => true, 'functions.updateFunctionDeployment' => true, - 'sites.createDeployment' => true, + 'sites.createVcsDeployment' => true, ]); } @@ -32,15 +34,15 @@ final class OnboardingTest extends TestCase $this->callback(function (Document $document): bool { $onboarding = $document->getAttribute('onboarding'); - return isset($onboarding['functions.createDeployment'], $onboarding['functions.updateFunctionDeployment']) - && $onboarding['functions.createDeployment']['status'] === ONBOARDING_STATUS_COMPLETED - && $onboarding['functions.createDeployment']['actorType'] === ACTOR_TYPE_SYSTEM - && ! empty($onboarding['functions.createDeployment']['at']); + return isset($onboarding['functions.createCliDeployment'], $onboarding['functions.updateFunctionDeployment']) + && $onboarding['functions.createCliDeployment']['status'] === ONBOARDING_STATUS_COMPLETED + && $onboarding['functions.createCliDeployment']['actorType'] === ACTOR_TYPE_SYSTEM + && ! empty($onboarding['functions.createCliDeployment']['at']); }) ); Onboarding::complete($dbForPlatform, $project, [ - 'functions.createDeployment', + 'functions.createCliDeployment', 'functions.updateFunctionDeployment', ], ACTOR_TYPE_SYSTEM); } @@ -52,13 +54,13 @@ final class OnboardingTest extends TestCase $dbForPlatform = $this->createMock(Database::class); $dbForPlatform->expects($this->never())->method('updateDocument'); - Onboarding::complete($dbForPlatform, $project, ['functions.createDeployment'], ACTOR_TYPE_SYSTEM); + Onboarding::complete($dbForPlatform, $project, ['functions.createCliDeployment'], ACTOR_TYPE_SYSTEM); } public function testIgnoresUnknownAndAlreadyCompletedMethods(): void { $project = new Document(['$id' => 'project1', 'onboarding' => [ - 'functions.createDeployment' => [ + 'functions.createCliDeployment' => [ 'status' => ONBOARDING_STATUS_COMPLETED, 'at' => '2026-01-01 00:00:00.000', 'actorType' => ACTOR_TYPE_USER, @@ -68,13 +70,13 @@ final class OnboardingTest extends TestCase $dbForPlatform = $this->createMock(Database::class); $dbForPlatform->expects($this->never())->method('updateDocument'); - Onboarding::complete($dbForPlatform, $project, ['functions.createDeployment', 'unknown.method'], ACTOR_TYPE_SYSTEM); + Onboarding::complete($dbForPlatform, $project, ['functions.createCliDeployment', 'unknown.method'], ACTOR_TYPE_SYSTEM); } public function testDoesNotOverwriteSkippedStage(): void { $project = new Document(['$id' => 'project1', 'onboarding' => [ - 'sites.createDeployment' => [ + 'sites.createVcsDeployment' => [ 'status' => ONBOARDING_STATUS_SKIPPED, 'at' => '2026-01-01 00:00:00.000', 'actorType' => ACTOR_TYPE_USER, @@ -84,6 +86,6 @@ final class OnboardingTest extends TestCase $dbForPlatform = $this->createMock(Database::class); $dbForPlatform->expects($this->never())->method('updateDocument'); - Onboarding::complete($dbForPlatform, $project, ['sites.createDeployment'], ACTOR_TYPE_SYSTEM); + Onboarding::complete($dbForPlatform, $project, ['sites.createVcsDeployment'], ACTOR_TYPE_SYSTEM); } } From d67b9c9326bd1ecf97bc6dd5abece02a88bf3820 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 05:15:07 +0000 Subject: [PATCH 3/9] test: add declare(strict_types=1) to OnboardingTest (Rector) --- tests/unit/Onboarding/OnboardingTest.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/unit/Onboarding/OnboardingTest.php b/tests/unit/Onboarding/OnboardingTest.php index 2ce7d2635d..e138e8e4ed 100644 --- a/tests/unit/Onboarding/OnboardingTest.php +++ b/tests/unit/Onboarding/OnboardingTest.php @@ -1,5 +1,7 @@ Date: Sun, 28 Jun 2026 05:30:27 +0000 Subject: [PATCH 4/9] refactor: inline deployment onboarding write, drop Onboarding helper Keep the existing inline read-modify-write pattern instead of a shared helper class. The builds worker writes the per-type deployment stages (and activation) directly via dbForPlatform; the API shutdown hook is unchanged from the base branch. Removes the Onboarding helper and its unit test. --- app/controllers/shared/api.php | 25 ++++- src/Appwrite/Onboarding/Onboarding.php | 70 -------------- .../Modules/Functions/Workers/Builds.php | 31 ++++++- tests/unit/Onboarding/OnboardingTest.php | 93 ------------------- 4 files changed, 52 insertions(+), 167 deletions(-) delete mode 100644 src/Appwrite/Onboarding/Onboarding.php delete mode 100644 tests/unit/Onboarding/OnboardingTest.php diff --git a/app/controllers/shared/api.php b/app/controllers/shared/api.php index 6f040fc4b5..e30305e55b 100644 --- a/app/controllers/shared/api.php +++ b/app/controllers/shared/api.php @@ -16,7 +16,6 @@ use Appwrite\Event\Webhook; use Appwrite\Extend\Exception; use Appwrite\Extend\Exception as AppwriteException; use Appwrite\Functions\EventProcessor; -use Appwrite\Onboarding\Onboarding; use Appwrite\Platform\Modules\Storage\Config\CacheControl; use Appwrite\Platform\Modules\Storage\Config\StorageCacheControl; use Appwrite\SDK\Method; @@ -24,6 +23,7 @@ use Appwrite\Usage\Context; use Appwrite\Utopia\Database\Documents\User; use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; +use Throwable; use Utopia\Abuse\Abuse; use Utopia\Bus\Bus; use Utopia\Cache\Adapter\Filesystem; @@ -1167,6 +1167,16 @@ Http::shutdown() return; } + $byMethod = $project->getAttribute('onboarding', []); + $status = \is_array($byMethod) ? ($byMethod[$method]['status'] ?? null) : null; + if ($status === ONBOARDING_STATUS_COMPLETED || $status === ONBOARDING_STATUS_SKIPPED) { + return; + } + + if (! \is_array($byMethod)) { + $byMethod = []; + } + $actorType = ($apiKey !== null && $apiKey->getRole() === User::ROLE_KEYS) ? match ($apiKey->getType()) { API_KEY_ACCOUNT => ACTOR_TYPE_KEY_ACCOUNT, @@ -1177,8 +1187,19 @@ Http::shutdown() : (! $user->isEmpty() ? ($mode === APP_MODE_ADMIN ? ACTOR_TYPE_ADMIN : ACTOR_TYPE_USER) : ACTOR_TYPE_GUEST); + $byMethod[$method] = [ + 'status' => ONBOARDING_STATUS_COMPLETED, + 'at' => DateTime::now(), + 'actorType' => $actorType, + ]; - $authorization->skip(fn () => Onboarding::complete($dbForPlatform, $project, [$method], $actorType)); + try { + $authorization->skip(fn () => $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ + 'onboarding' => $byMethod, + ]))); + } catch (Throwable) { + // Missing `onboarding` attribute on upgraded installs must not break the request lifecycle. + } }); Http::init() diff --git a/src/Appwrite/Onboarding/Onboarding.php b/src/Appwrite/Onboarding/Onboarding.php deleted file mode 100644 index 555c3a10be..0000000000 --- a/src/Appwrite/Onboarding/Onboarding.php +++ /dev/null @@ -1,70 +0,0 @@ - $methods - */ - public static function complete(Database $dbForPlatform, Document $project, array $methods, string $actorType): void - { - if ($project->getId() === 'console' || $methods === []) { - return; - } - - $onboarding = Config::getParam('onboarding', []); - - $byMethod = $project->getAttribute('onboarding', []); - if (! \is_array($byMethod)) { - $byMethod = []; - } - - $changed = false; - foreach ($methods as $method) { - if (! isset($onboarding[$method])) { - continue; - } - - $status = $byMethod[$method]['status'] ?? null; - if ($status === ONBOARDING_STATUS_COMPLETED || $status === ONBOARDING_STATUS_SKIPPED) { - continue; - } - - $byMethod[$method] = [ - 'status' => ONBOARDING_STATUS_COMPLETED, - 'at' => DateTime::now(), - 'actorType' => $actorType, - ]; - $changed = true; - } - - if (! $changed) { - return; - } - - try { - $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'onboarding' => $byMethod, - ])); - } catch (Throwable) { - // Missing `onboarding` attribute on upgraded installs must not break the caller. - } - } -} diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 35ae9948d8..1a64ce235e 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -13,7 +13,6 @@ use Appwrite\Event\Realtime; use Appwrite\Event\Webhook; use Appwrite\Extend\Exception as AppwriteException; use Appwrite\Filter\BranchDomain as BranchDomainFilter; -use Appwrite\Onboarding\Onboarding; use Appwrite\Usage\Context; use Appwrite\Utopia\Response\Model\Deployment; use Appwrite\Vcs\Comment; @@ -1076,8 +1075,36 @@ class Builds extends Action if ($activateBuild && $activateStage !== null) { $stages[] = $activateStage; } + if ($stages !== []) { - Onboarding::complete($dbForPlatform, $project, $stages, ACTOR_TYPE_SYSTEM); + $onboarding = $project->getAttribute('onboarding', []); + if (! \is_array($onboarding)) { + $onboarding = []; + } + + $onboardingChanged = false; + foreach ($stages as $stage) { + $stageStatus = $onboarding[$stage]['status'] ?? null; + if ($stageStatus === ONBOARDING_STATUS_COMPLETED || $stageStatus === ONBOARDING_STATUS_SKIPPED) { + continue; + } + $onboarding[$stage] = [ + 'status' => ONBOARDING_STATUS_COMPLETED, + 'at' => DateTime::now(), + 'actorType' => ACTOR_TYPE_SYSTEM, + ]; + $onboardingChanged = true; + } + + if ($onboardingChanged) { + try { + $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ + 'onboarding' => $onboarding, + ])); + } catch (\Throwable) { + // Missing `onboarding` attribute on upgraded installs must not break the build lifecycle. + } + } } $resource = $this->updateLatestDeployment($dbForProject, $resource); diff --git a/tests/unit/Onboarding/OnboardingTest.php b/tests/unit/Onboarding/OnboardingTest.php deleted file mode 100644 index e138e8e4ed..0000000000 --- a/tests/unit/Onboarding/OnboardingTest.php +++ /dev/null @@ -1,93 +0,0 @@ - true, - 'functions.createCliDeployment' => true, - 'functions.createVcsDeployment' => true, - 'functions.updateFunctionDeployment' => true, - 'sites.createVcsDeployment' => true, - ]); - } - - public function testCompletesMultipleStagesInASingleWrite(): void - { - $project = new Document(['$id' => 'project1', 'onboarding' => []]); - - $dbForPlatform = $this->createMock(Database::class); - $dbForPlatform->expects($this->once()) - ->method('updateDocument') - ->with( - 'projects', - 'project1', - $this->callback(function (Document $document): bool { - $onboarding = $document->getAttribute('onboarding'); - - return isset($onboarding['functions.createCliDeployment'], $onboarding['functions.updateFunctionDeployment']) - && $onboarding['functions.createCliDeployment']['status'] === ONBOARDING_STATUS_COMPLETED - && $onboarding['functions.createCliDeployment']['actorType'] === ACTOR_TYPE_SYSTEM - && ! empty($onboarding['functions.createCliDeployment']['at']); - }) - ); - - Onboarding::complete($dbForPlatform, $project, [ - 'functions.createCliDeployment', - 'functions.updateFunctionDeployment', - ], ACTOR_TYPE_SYSTEM); - } - - public function testIgnoresConsoleProject(): void - { - $project = new Document(['$id' => 'console', 'onboarding' => []]); - - $dbForPlatform = $this->createMock(Database::class); - $dbForPlatform->expects($this->never())->method('updateDocument'); - - Onboarding::complete($dbForPlatform, $project, ['functions.createCliDeployment'], ACTOR_TYPE_SYSTEM); - } - - public function testIgnoresUnknownAndAlreadyCompletedMethods(): void - { - $project = new Document(['$id' => 'project1', 'onboarding' => [ - 'functions.createCliDeployment' => [ - 'status' => ONBOARDING_STATUS_COMPLETED, - 'at' => '2026-01-01 00:00:00.000', - 'actorType' => ACTOR_TYPE_USER, - ], - ]]); - - $dbForPlatform = $this->createMock(Database::class); - $dbForPlatform->expects($this->never())->method('updateDocument'); - - Onboarding::complete($dbForPlatform, $project, ['functions.createCliDeployment', 'unknown.method'], ACTOR_TYPE_SYSTEM); - } - - public function testDoesNotOverwriteSkippedStage(): void - { - $project = new Document(['$id' => 'project1', 'onboarding' => [ - 'sites.createVcsDeployment' => [ - 'status' => ONBOARDING_STATUS_SKIPPED, - 'at' => '2026-01-01 00:00:00.000', - 'actorType' => ACTOR_TYPE_USER, - ], - ]]); - - $dbForPlatform = $this->createMock(Database::class); - $dbForPlatform->expects($this->never())->method('updateDocument'); - - Onboarding::complete($dbForPlatform, $project, ['sites.createVcsDeployment'], ACTOR_TYPE_SYSTEM); - } -} From 4fc1f737b6a527545761187cd8691bdf91893131 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 05:37:20 +0000 Subject: [PATCH 5/9] fix(builds): re-read project before marking deployment onboarding The injected $project is a job-dispatch-time snapshot and a build can run for minutes. Read the current onboarding map from dbForPlatform before writing so a stage skipped or completed via the API during the build is not overwritten. --- .../Platform/Modules/Functions/Workers/Builds.php | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 1a64ce235e..7de85fbb91 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -1077,7 +1077,12 @@ class Builds extends Action } if ($stages !== []) { - $onboarding = $project->getAttribute('onboarding', []); + // Re-read the project: the injected $project is a snapshot from + // job-dispatch time, and a build can run for minutes. Reading the + // current onboarding map avoids overwriting a stage that was + // skipped (or completed) via the API while the build was running. + $onboardingProject = $dbForPlatform->getDocument('projects', $project->getId()); + $onboarding = $onboardingProject->getAttribute('onboarding', []); if (! \is_array($onboarding)) { $onboarding = []; } @@ -1096,7 +1101,7 @@ class Builds extends Action $onboardingChanged = true; } - if ($onboardingChanged) { + if ($onboardingChanged && ! $onboardingProject->isEmpty()) { try { $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ 'onboarding' => $onboarding, From 0fe49223b773556d82b2380bd33f10f19442f664 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 05:48:26 +0000 Subject: [PATCH 6/9] refactor(builds): simplify onboarding write to fetch + set + update Use null-coalescing assignment so only stages not already recorded are set, which inherently leaves a skipped/completed stage untouched. Drops the explicit status guard, changed flag, and isEmpty check. --- .../Modules/Functions/Workers/Builds.php | 31 ++++++------------- 1 file changed, 10 insertions(+), 21 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 7de85fbb91..0ddb14aef1 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -1077,38 +1077,27 @@ class Builds extends Action } if ($stages !== []) { - // Re-read the project: the injected $project is a snapshot from - // job-dispatch time, and a build can run for minutes. Reading the - // current onboarding map avoids overwriting a stage that was - // skipped (or completed) via the API while the build was running. - $onboardingProject = $dbForPlatform->getDocument('projects', $project->getId()); - $onboarding = $onboardingProject->getAttribute('onboarding', []); + // Fetch the project fresh and only set stages that aren't already + // recorded, so a stage skipped or completed via the API while the + // build was running is left untouched (??= respects it). + $onboarding = $dbForPlatform->getDocument('projects', $project->getId())->getAttribute('onboarding', []); if (! \is_array($onboarding)) { $onboarding = []; } - $onboardingChanged = false; foreach ($stages as $stage) { - $stageStatus = $onboarding[$stage]['status'] ?? null; - if ($stageStatus === ONBOARDING_STATUS_COMPLETED || $stageStatus === ONBOARDING_STATUS_SKIPPED) { - continue; - } - $onboarding[$stage] = [ + $onboarding[$stage] ??= [ 'status' => ONBOARDING_STATUS_COMPLETED, 'at' => DateTime::now(), 'actorType' => ACTOR_TYPE_SYSTEM, ]; - $onboardingChanged = true; } - if ($onboardingChanged && ! $onboardingProject->isEmpty()) { - try { - $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'onboarding' => $onboarding, - ])); - } catch (\Throwable) { - // Missing `onboarding` attribute on upgraded installs must not break the build lifecycle. - } + try { + $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ + 'onboarding' => $onboarding, + ])); + } catch (\Throwable) { } } From aacab8fcf107e72c4491be14f66502f943984ced Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 06:27:02 +0000 Subject: [PATCH 7/9] feat(projects): track template & duplicate deployment onboarding via the API hook Add functions/sites createTemplateDeployment and createDuplicateDeployment to the onboarding config so the existing api.php shutdown hook marks them in the API request context (which reaches the central console DB), instead of the regional build worker. Reverts the build-worker write and the Onboarding helper. --- app/config/onboarding.php | 20 +++--- app/init/constants.php | 1 - .../Modules/Functions/Workers/Builds.php | 62 ------------------- 3 files changed, 10 insertions(+), 73 deletions(-) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 5b73328e25..6ac29b25ee 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -40,11 +40,11 @@ return [ // Functions 'functions.create' => true, - // One key per deployment creation type (deployment `type` attribute); - // OR them in the UI for a single "created a deployment" milestone. - 'functions.createManualDeployment' => true, - 'functions.createCliDeployment' => true, - 'functions.createVcsDeployment' => true, + // One key per deployment-creation SDK method; OR them in the UI for a + // single "created a deployment" milestone. + 'functions.createDeployment' => true, + 'functions.createTemplateDeployment' => true, + 'functions.createDuplicateDeployment' => true, 'functions.updateFunctionDeployment' => true, // Messaging @@ -67,10 +67,10 @@ return [ // Sites 'sites.create' => true, - // One key per deployment creation type (deployment `type` attribute); - // OR them in the UI for a single "created a deployment" milestone. - 'sites.createManualDeployment' => true, - 'sites.createCliDeployment' => true, - 'sites.createVcsDeployment' => true, + // One key per deployment-creation SDK method; OR them in the UI for a + // single "created a deployment" milestone. + 'sites.createDeployment' => true, + 'sites.createTemplateDeployment' => true, + 'sites.createDuplicateDeployment' => true, 'sites.updateSiteDeployment' => true, ]; diff --git a/app/init/constants.php b/app/init/constants.php index 62819d601b..9efb6e3222 100644 --- a/app/init/constants.php +++ b/app/init/constants.php @@ -171,7 +171,6 @@ const ACTOR_TYPE_GUEST = 'guest'; const ACTOR_TYPE_KEY_PROJECT = 'keyProject'; const ACTOR_TYPE_KEY_ACCOUNT = 'keyAccount'; const ACTOR_TYPE_KEY_ORGANIZATION = 'keyOrganization'; -const ACTOR_TYPE_SYSTEM = 'system'; /** * Project onboarding stage status (stored per SDK method key under project.onboarding JSON). diff --git a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php index 0ddb14aef1..d0806ccadf 100644 --- a/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php +++ b/src/Appwrite/Platform/Modules/Functions/Workers/Builds.php @@ -1039,68 +1039,6 @@ class Builds extends Action Span::add('build.activated', true); } - /** - * Mark deployment onboarding stages. Done here (not via the HTTP sdk - * label) so every creation path - manual upload, CLI, template, - * duplicate and VCS - and the worker-driven activation are covered. - * The create stage is keyed by the deployment `type` so each type - * has its own stage (OR them in the UI for a single milestone). - */ - $collection = $resource->getCollection(); - $createStage = match ($collection) { - 'functions' => match ($deployment->getAttribute('type')) { - 'manual' => 'functions.createManualDeployment', - 'cli' => 'functions.createCliDeployment', - 'vcs' => 'functions.createVcsDeployment', - default => null, - }, - 'sites' => match ($deployment->getAttribute('type')) { - 'manual' => 'sites.createManualDeployment', - 'cli' => 'sites.createCliDeployment', - 'vcs' => 'sites.createVcsDeployment', - default => null, - }, - default => null, - }; - $activateStage = match ($collection) { - 'functions' => 'functions.updateFunctionDeployment', - 'sites' => 'sites.updateSiteDeployment', - default => null, - }; - - $stages = []; - if ($createStage !== null) { - $stages[] = $createStage; - } - if ($activateBuild && $activateStage !== null) { - $stages[] = $activateStage; - } - - if ($stages !== []) { - // Fetch the project fresh and only set stages that aren't already - // recorded, so a stage skipped or completed via the API while the - // build was running is left untouched (??= respects it). - $onboarding = $dbForPlatform->getDocument('projects', $project->getId())->getAttribute('onboarding', []); - if (! \is_array($onboarding)) { - $onboarding = []; - } - - foreach ($stages as $stage) { - $onboarding[$stage] ??= [ - 'status' => ONBOARDING_STATUS_COMPLETED, - 'at' => DateTime::now(), - 'actorType' => ACTOR_TYPE_SYSTEM, - ]; - } - - try { - $dbForPlatform->updateDocument('projects', $project->getId(), new Document([ - 'onboarding' => $onboarding, - ])); - } catch (\Throwable) { - } - } - $resource = $this->updateLatestDeployment($dbForProject, $resource); $this->afterDeploymentSuccess( From 808a5f53dfb5a8b834331c2c31565f9bc6351f02 Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 06:30:36 +0000 Subject: [PATCH 8/9] feat(projects): drop createDuplicateDeployment from onboarding Duplicating an existing deployment is a redeploy/rollback action that presupposes a prior deployment, so it is not an onboarding milestone. Keeps createDeployment + createTemplateDeployment for functions and sites. --- app/config/onboarding.php | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 6ac29b25ee..4f51d95e02 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -40,11 +40,10 @@ return [ // Functions 'functions.create' => true, - // One key per deployment-creation SDK method; OR them in the UI for a - // single "created a deployment" milestone. + // Deployment-creation SDK methods; OR them in the UI for a single + // "created a deployment" milestone. 'functions.createDeployment' => true, 'functions.createTemplateDeployment' => true, - 'functions.createDuplicateDeployment' => true, 'functions.updateFunctionDeployment' => true, // Messaging @@ -67,10 +66,9 @@ return [ // Sites 'sites.create' => true, - // One key per deployment-creation SDK method; OR them in the UI for a - // single "created a deployment" milestone. + // Deployment-creation SDK methods; OR them in the UI for a single + // "created a deployment" milestone. 'sites.createDeployment' => true, 'sites.createTemplateDeployment' => true, - 'sites.createDuplicateDeployment' => true, 'sites.updateSiteDeployment' => true, ]; From 971c74bddec6b32efa83252a6cf2dbeace74d41e Mon Sep 17 00:00:00 2001 From: Damodar Lohani Date: Sun, 28 Jun 2026 06:32:53 +0000 Subject: [PATCH 9/9] feat(projects): track VCS deployment onboarding (repo-connected deploy) Add functions/sites createVcsDeployment - the explicit 'deploy from connected repo' endpoint - so connecting a repo to ship a first function/site marks an onboarding stage. Caught by the api hook (API context), like the other methods. --- app/config/onboarding.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/app/config/onboarding.php b/app/config/onboarding.php index 4f51d95e02..014301a72e 100644 --- a/app/config/onboarding.php +++ b/app/config/onboarding.php @@ -44,6 +44,7 @@ return [ // "created a deployment" milestone. 'functions.createDeployment' => true, 'functions.createTemplateDeployment' => true, + 'functions.createVcsDeployment' => true, 'functions.updateFunctionDeployment' => true, // Messaging @@ -70,5 +71,6 @@ return [ // "created a deployment" milestone. 'sites.createDeployment' => true, 'sites.createTemplateDeployment' => true, + 'sites.createVcsDeployment' => true, 'sites.updateSiteDeployment' => true, ];