Deploy an app

This is the app-owner loop for an app that already exists in Via. Start from the Vary project you want to deploy.

vary target add prod https://vary.example.com
vary login --target prod --name alice --token-stdin
vary app deploy my-api --target prod --apply-manifest
vary app deploy my-api --target prod --resume
vary app smoke my-api --target prod

Via deploys committed source. It checks out a clean copy, typechecks and tests it, builds and signs the artifact, launches the runtime container, provides config and add-on bindings, and attaches public traffic after route and domain gates pass.

Connect to Via

Register the Via host as a named target, then exchange the one-time adm_... token from the operator for a short-lived user session:

vary target add prod https://vary.example.com
vary login --target prod --name alice --token-stdin

The workstation stores the resulting session under ~/.vary/credentials/sessions/<slug>.json with mode 0600. The admin token is single-use and should not be needed again unless the operator mints another one.

Project requirements

Your project needs a normal vary.toml with build metadata. Via reads the app name and build entry from the project and applies any via.app.toml manifest during deploy.

By default, Via builds with the selected concrete toolchain from varyup. Add [build].toolchain = "<version>" only when you intentionally want to pin an installed version for that app.

For subtree deployments that contain repo-local and repo-root-only tests, set [deploy].test_pattern to the app-local test file or glob Via should run in the clean checkout, for example:

[deploy]
test_pattern = "tests/test_issue_api.vary"

Stage a clean deploy repo

Via deploys committed source from a clean Git working tree. When your working project carries uncommitted changes or build output you do not want to ship, stage a dedicated checkout and deploy from it with --workdir. This keeps the deploy snapshot reproducible and avoids pushing unrelated generated files.

# Stage a clean copy of the source you want to deploy
git clone --depth 1 file:///path/to/project /tmp/my-api-deploy
cd /tmp/my-api-deploy

# Configure a repo-local Git identity for the snapshot commit
git config user.name "Deploy Bot"
git config user.email "deploy@example.com"

git add -A
git commit -m "deploy snapshot"

vary app deploy my-api --target prod --workdir /tmp/my-api-deploy --apply-manifest

Set the identity with the repo-local git config user.name and git config user.email shown above rather than a host-wide identity, so a shared or ephemeral build host never inherits or overwrites the operator's account-wide Git settings. Deploying from a staged checkout limits the build input to the files you committed, instead of unrelated generated files left behind in your working project.

Deploy

From the Vary project root:

vary app deploy my-api --target prod --apply-manifest

What the command does:

Step	Action
1	Resolves the named target and cached session.
2	Finds `vary.toml` by searching upward from the current directory.
3	Requires a Git working tree.
4	Rejects dirty working trees by default.
5	Applies `via.app.toml` when `--apply-manifest` or `--resume` is passed.
6	Checks manifest readiness before source push.
7	Mints a one-use deploy token.
8	Pushes current `HEAD` to the Via-hosted app repository.
9	Streams deploy status until a terminal state is reached.

Deploy tokens are short-lived and scoped to the app, repository, and ref. The token is not written to normal Git credential storage.

Resume gates

If a manifest-declared hostname requires approval, deploy stops before source push with pending_admin_approval. The output names the app, hostname, request id, admin command, and resume command:

via domain approve my-api my-api.apps.example.com
vary app deploy my-api --target prod --resume

Later redeploys with the same approved hostname do not need admin involvement:

vary app deploy my-api --target prod
vary app smoke my-api --target prod

No-op and rebuilds

If Git reports that the branch is already up to date and Via can confirm the current release was built from the same source and config profile inputs, deploy exits as a no-op instead of queueing another build.

Force a rebuild only when you intentionally want to retest unchanged source or refresh runtime artifacts:

vary app deploy my-api --target prod --force-rebuild