ts-deploy

ts-deploy is TerraScale's thin CI and delivery helper for Forgejo Actions. Every repository workflow calls one central reusable workflow — .forgejo/workflows/deploy.yml in this repository — and that workflow installs the version-pinned release binary, verifies both downloaded digests, and runs ts-deploy ci --repo <name> (D-68). The repository kinds and their check, build, test, publish, and hand-off steps live in Go here and change in one place.

TerraScale.Orchestrator alone authorizes and performs production rollout, health checks, routing changes, and rollback. This CLI never contacts cluster members or owns rollout state.

Commands

• ts-deploy ci --repo <name> runs the repository's declared verification set.
• ts-deploy ci resolve-cli records the executable and version used by a workflow.
• ts-deploy ci validate validates repository and workflow metadata.
• ts-deploy deploy validates an artifact request and submits it through the versioned Orchestrator contract (--dry-run performs local validation only).
• ts-deploy delivery-status --operation-id <id> polls a terminal delivery receipt after a lost submit response.
• ts-deploy delivery-recover --operation-id <id> safely closes an abandoned operation after its owner lease expires.
• ts-deploy forgejo failures reports failed, running, and cancelled Forgejo jobs across configured repositories.
• ts-deploy forgejo release list|view|publish|download owns the release lifecycle: it lists releases, binds an existing release tag to an exact commit, publishes assets idempotently, and verifies a downloaded SHA-256.
• ts-deploy forgejo issue list|open|comment|close searches and mutates issues, applying labels after creation.
• ts-deploy forgejo actions tasks|dispatch|variables inspects Action tasks, triggers a workflow on an exact ref, and lists repository variables.
• ts-deploy sdk validate validates SDK and package repositories.
• ts-deploy cache status and ts-deploy cache prune inspect and maintain persistent build caches.
• ts-deploy doctor checks and repairs the builder toolchain.
• ts-deploy version prints the CLI version.

Forgejo operations run through the pinned fj CLI, which owns the host, credential store, and output format; the CLI never speaks the Forgejo API for mutations. The legacy failure inventory may additionally use an explicit FORGEJO_TOKEN. forgejo release, forgejo issue, and forgejo actions accept --host, --repo owner/name, and --json where a structured result exists. Issue comment, close, and label edits resolve their repository from a local checkout, so they take --repository-root and refuse a checkout that belongs to another repository. See docs/forgejo.md.

deploy --dry-run validates and prints a request without contacting Orchestrator. A live request needs TERRASCALE_ORCHESTRATOR_DELIVERY_URL or --orchestrator-url. TERRASCALE_ORCHESTRATOR_TOKEN is sent only to that explicit endpoint.

Repository workflow

A consumer repository keeps one job that calls the central reusable workflow:

jobs:
  ci:
    uses: TerraScale/ts-deploy/.forgejo/workflows/deploy.yml@main
    with:
      repo: ts-landing
    secrets: inherit

The callee runs in the caller's context: it checks out the caller's repository at the exact event SHA, installs the version-pinned ts-deploy release binary (both downloaded digests verified), and runs ts-deploy ci --repo <name>. The caller owns its permissions (contents: write for its release lane, issues: write for the PR preview comment) and passes its secrets through secrets: inherit; the reusable workflow binds vars.TS_DEPLOY_VERSION, TS_DEPLOY_SHA256, and TS_DEPLOY_SIGNATURE_SHA256 itself. See .forgejo/workflows/deploy.yml for the exact checkout, download, verification, and invocation steps.

The CLI release identity stays in TS_DEPLOY_VERSION, TS_DEPLOY_SHA256, and TS_DEPLOY_SIGNATURE_SHA256, so a new CLI release ships by changing those variables rather than editing a workflow, and a moving release tag can never change the executable a job consumes. ts-orchestrator additionally passes terrabase_rev so the reusable workflow checks out the pinned TerraBase sibling; ts-deploy itself runs its reviewed source with go run ./cmd/ts-deploy ci --repo ts-deploy so a broken published CLI cannot block its replacement.

RepositoryCIWorkflow in internal/cli/workflow/repository_ci_workflow.go generates each repository's .forgejo/workflows/ci.yml, and a drift test keeps the checked-in files identical to the generator.

Supported repositories

Release plans cover native binaries, engine contracts, Workers, documentation, and customer SDK packages.

For Workers, the repository's pinned Wrangler resolves the generated Vinext configuration when present and dry-runs the upload bundle. CI captures those modules, binding configuration, and static assets into a relocatable candidate, checks it with --no-bundle, and signs its deterministic archive. After Forgejo publication and signature verification, CI extracts that archive into a fresh directory and runs only wrangler versions upload --no-bundle. No package build hook runs during publication, and this upload does not route traffic. Missing build outputs stop before publication; retries recreate only marked private workspaces and verify the extracted file inventory, so stale modules cannot survive an interrupted upload.

For the TypeScript SDK, CI runs the checkout checks, packs once with npm pack --ignore-scripts, and passes that exact tarball to scripts/qualify-npm-artifact.ts --release --tarball <absolute-path>. The qualifier checks a clean installed consumer and public package metadata. Archives are bounded to 64 MiB and must retain the same digest throughout qualification. A failed check or changed archive stops publication.

The resulting tarball is signed and uploaded to Forgejo, verified again, and published with npm publish <same-tarball> --ignore-scripts before candidate handoff. Release never rebuilds or repacks the checkout at publication time. An interrupted or failed publication stops before handoff; it does not authorize rollout. See the SDK's release guide.

See:

• docs/workflow-policy.md
• docs/adr/README.md
• ../GOAL.md, the workspace authority