For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add -g @git.zone/tsdeploy

Usage

tsdeploy stores a small local deployment pointer and uses Cloudly as the source of truth for workload deployment state. Cloudly workload deploys validate the linked service and registry target, then build and push the OCI image that Cloudly deploys through deployOnPush.

Create or update a local profile in the user config store:

tsdeploy login --profile prod --target cloudly --origin https://cloudly.example.com

To persist a Cloudly token in the profile store, pass it explicitly. Stored tokens are encrypted as single smartconfig SSH-agent secrets. The matching ssh-ed25519 key must be available from ssh-agent when saving the token and when decrypting it during deploy:

tsdeploy login --profile prod --target cloudly --origin https://cloudly.example.com --token ...

By default, token encryption uses ~/.ssh/id_ed25519.pub as the authorized-key hint. To use a different public key, pass an authorized public key file or set TSDEPLOY_SSH_PUBLIC_KEY_PATH:

tsdeploy login --profile prod --target cloudly --origin https://cloudly.example.com --token ... --ssh-public-key-path ~/.ssh/id_ed25519.pub

Link a project to a Cloudly or Onebox pointer. Cloudly workload deploys require serviceId; deploymentId is optional status context only. Use either init for the first pointer write or link to replace the current pointer:

tsdeploy init --profile prod --serviceId service-123
# or
tsdeploy link --profile prod --serviceId service-123 --deploymentId deployment-123

Inspect current local state:

tsdeploy status
tsdeploy doctor
tsdeploy plan

Deploy a linked Cloudly workload:

tsdeploy deploy

Useful deploy flags:

tsdeploy deploy --dryRun
tsdeploy deploy --allowDirty
tsdeploy deploy --tag latest --platform linux/amd64
tsdeploy deploy --builder default-builder
tsdeploy deploy --skipChecks
tsdeploy deploy --skipPush
tsdeploy deploy --verifyUrl https://app.example.com --waitSeconds 120

Without --builder, deploy provisions and uses a persistent docker-container buildx builder named tsdeploy-builder (created on first use). This makes --push a single BuildKit registry push instead of the docker driver's build-plus-daemon-push, which could fail a deploy after the image had already landed. If a builder named tsdeploy-builder already exists with a different driver, deploy fails with instructions to remove it (docker buildx rm tsdeploy-builder) or pass --builder explicitly.

The project pointer is written to .nogit/tsdeploy.json and is intentionally small:

{
  "schemaVersion": 1,
  "profile": "prod",
  "serviceId": "service-123",
  "deploymentId": "deployment-123"
}

Profiles are stored in the user smartconfig key-value store. Tokens are never printed by status, doctor, or plan.

Current Scope

Implemented deployment scope is Cloudly workload image deployment only. tsdeploy deploy does not create App Store installs, perform Cloudly service upgrades, run Onebox installs, or duplicate gitzone release / tsdocker release semantics.

For a real Cloudly deploy, credentials can be provided through a saved encrypted profile token or one of these deploy-time inputs:

TSDEPLOY_TOKEN=... tsdeploy deploy
tsdeploy deploy --token ...
TSDEPLOY_CLOUDLY_USERNAME=... TSDEPLOY_CLOUDLY_PASSWORD=... tsdeploy deploy
tsdeploy deploy --username ... --password ...
CLOUDLY_USERNAME=... CLOUDLY_PASSWORD=... tsdeploy deploy

deploy refuses to push when the linked Cloudly service has deployOnPush disabled or when an explicit --image does not match Cloudly's registry target for the service. Docker build-arg values configured in .smartconfig.json must be available as environment variables; values are passed through the process environment and are not printed in JSON output.

Mutable deploys also require a clean git working tree by default. Commit or stash local changes before deploying, or pass --allowDirty for an explicit override.

--dryRun contacts Cloudly to validate the linked service and resolve the exact registry target image, then skips project checks and Docker commands.

Onebox deployment mutations are intentionally not implemented until the exact Onebox deployment APIs are verified upstream.

Programmatic API

import { TsDeploy } from '@git.zone/tsdeploy';

const tsDeploy = new TsDeploy({ projectDir: process.cwd() });

await tsDeploy.saveProfile({
  name: 'prod',
  target: 'cloudly',
  origin: 'https://cloudly.example.com',
});

await tsDeploy.writeProjectLink({
  profile: 'prod',
  serviceId: 'service-123',
});

const plan = await tsDeploy.buildPlan();
console.log(plan.mutationAllowed); // true for linked Cloudly workloads

const result = await tsDeploy.deploy({
  dryRun: true,
  token: process.env.TSDEPLOY_TOKEN,
});
console.log(result.image);

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license.md file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@git.zone/tsdeploy

Issue Reporting and Security