Zozo Docs

Create a Hosted Stack with Onramp ​

An Onramp creates a new hosted Stack from the portable parts of a Self-hosted Stack. The source keeps working as a separate peer after the Onramp finishes.

What Crosses ​

An Onramp carries:

  • Settings.
  • Projects that have a git remote, including Bitbucket host-qualified keys such as bitbucket.org/team/repo. The review screen lists Projects that will be skipped because they have no remote.
  • Agent Bundle names.
  • A Credential Placeholder for each unarchived Credential named by a Project's Credential Route or the Guide Credential. Each placeholder keeps the Credential name, Provider, and kind, but no authentication material.
  • Jira tracker bindings, including the Jira site, project key, Publish Issue Type, optional Spec Issue Type, component, and labels. Medium Intake and Wayfinder require a Spec Issue Type; Small Intake can run without it.
  • The Environments you choose, including their Variables.

The review screen identifies each Environment by name and shows its Variable names and the Projects that pin it. Environment values are sealed before the bundle leaves the source Stack, so the service holding the bundle can't read them.

An Onramp doesn't carry:

  • Credential authentication material. Ambient Credentials remain on a Local Stack, and provisioned Credentials remain on any other Self-hosted Stack.
  • Platform Credentials, the secrets authenticating the Dispatcher to GitHub or Atlassian. Setup asks for them again, with no Credential Placeholder. Older bundles' tracker placeholders are ignored.
  • Workspaces, including work in progress in those directories.
  • Threads, Runs, and Event history.

The hosted Stack is therefore a fresh place for new work. Keep the source Stack if you still need its history or local Workspace contents. If you need a separate copy of your history, see Export Your Data.

Start from the Self-hosted Stack ​

  1. Open the source Stack's Dashboard and go to Settings (#/settings).
  2. In Hosted Stack, select See what crosses.
  3. Review the Settings, Project names, agent bundle names, and each Credential Placeholder with its Provider and kind. Check the list of Projects with no git remote, since those Projects won't cross. An Archived Credential never becomes a placeholder. If a Credential Route names one, the Route still crosses unchanged and the review warns that it will arrive unresolved.
  4. Under Choose Environments, select every Environment you want on the hosted Stack. An unselected Environment doesn't cross, and a Project that used it arrives without that Environment pinned.
  5. Select Create hosted Stack.

The Dashboard submits the Onramp and opens the Tenant App in a new tab. If the tab doesn't open, or if you need to return later, use the Continue in the Tenant App link in the pending Onramp panel.

Keep the source Dashboard available until Setup is complete. If you selected any Environments, the pending panel also shows an Environment key. The Tenant App normally carries this key through the browser session without putting it in the hosted service's readable URL data. You can copy it from the source Stack if Setup later asks for it.

Continue While Signed Out ​

The Onramp link opens a single Continue Onramp with GitHub action. You don't need an invite code.

  1. Select Continue Onramp with GitHub and use the GitHub identity that should own or join the hosted Tenant.
  2. If that identity has no Zozo account, complete the normal account steps: choose the permanent slug and Home Region, then complete Checkout.
  3. Wait while the first hosted Stack is provisioned. It is built from the pending Onramp rather than as an empty Stack.
  4. Open the new Stack's Dashboard when it becomes available.

If the GitHub identity already belongs to a Tenant, signing in follows the existing-Tenant path below instead of creating another Tenant.

Continue While Signed In ​

Opening the link with an active Tenant App session accepts the Onramp for that Tenant. Acceptance doesn't modify an existing Stack. It makes the Onramp the source for the next Stack you add.

  1. Review the Onramp notice on All Stacks. It confirms that Settings and Projects will come from the Self-hosted Stack.
  2. Complete Add a Stack: choose its permanent Stack name and plan, review the prorated amount, and confirm.
  3. Wait for provisioning, then select Open on the new Stack.

Your account must be eligible to add another Stack. A Stack already being provisioned must finish, and the Tenant must have room under its Stack limit. The Tenant App explains the applicable blocker. The Onramp remains pending while you resolve it, up to its expiry.

If you accept another Onramp before adding a Stack, the newer one becomes the source for the next Stack. The earlier one remains pending and can still be revisited until it expires.

Finish Setup on the Hosted Stack ​

The new Stack starts in Setup even though its portable state has arrived.

  1. Resolve every imported Credential Placeholder. Select Provision <name> to connect a new Credential of the shown Provider and kind, or Discard if you no longer want it. Setup can't finish while a placeholder remains. Discarding one leaves Projects that name it unable to create Runs until you repair their Credential Route.
  2. If Unlock your Onramp Environments appears, paste the Environment key from the source Stack and select Unlock Environments. This fallback appears when the key did not arrive with the browser session.
  3. Complete any remaining Setup steps for a Runtime Credential, a Platform Credential for every watched Project's Platform, and a Project. An Atlassian Project waits until both its Bitbucket and Jira tokens read valid. Imported state can satisfy some checklist items, but Credentials always need to be connected on the hosted Stack.
  4. Review Stack ready, then start Dispatching or go to the Dashboard.

If the bundle can't be applied, the hosted Stack still starts and Setup says that it started empty. If a newer bundle contains items this Stack doesn't understand, Setup identifies the skipped items so you can configure them manually.

Cancel or Let It Expire ​

While the Onramp is pending, select Cancel Onramp on the source Stack to discard the waiting bundle. Cancellation doesn't change the source Stack. An open Tenant App link will report that the Onramp was cancelled, and you must start a new Onramp if you change your mind.

An unclaimed Onramp expires 30 days after it starts. Its waiting bundle is discarded, the old link reports that it expired, and no Stack can be created from it. Return to Settings on the source Stack and start a new Onramp.

Once a new Stack has claimed the Onramp, it is complete and can no longer be cancelled or reused to create another Stack. The source Stack's panel links to the hosted Stack.

Docs for Zozo: a coding-agent harness.

Copyright © Zozo