Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Queue the intended source revision and receive a verified build and active deployment result.

​
Prerequisites

  • An authenticated profile
  • An existing StackShift project
  • A connected repository for Git deployments

​
Workflow

1
Select the project by argument, global flag, or profile default.
2
Choose a Git ref or a local directory.
3
Review the local upload preview when applicable.
4
Follow build output and wait for the matching active deployment.
5
Use --detach only when another process will monitor the build.

​
Deploy a Git branch, tag, or commit

--ref is sent unchanged to the project build contract. Use a branch, tag, or commit understood by the connected repository. When omitted, the server applies the project build default.

​
Deploy a local directory

With --local, the CLI creates a deterministic gzip-compressed tar archive, uploads it as a source revision, and uses the build returned by that upload.

​
Ignore rules

The CLI applies built-in exclusions, then reads .gitignore and .stackshiftignore from the selected root. Blank lines and comments are ignored. Leading / is removed before matching.
  • Always excluded: .git, nested .git content, node_modules, and .cache.
  • Excluded by default: .env and .env.*.
  • Included again by default: .env.example and .env.sample.
  • Additional Docker-style patterns can be placed in .stackshiftignore.
  • Archive paths are sorted.
  • Tar and gzip timestamps are normalized to the Unix epoch.
  • Ownership names and numeric user and group IDs are normalized.
  • Absolute symlinks are rejected.
  • Relative symlinks that resolve outside the selected root are rejected.
  • Sockets, devices, and other unsupported source file types are rejected.

​
Upload preview and limits

Before upload, the CLI writes the included file count, compressed bytes, and SHA-256 digest to standard error. It uses the server capability upload limit; if the server does not provide one, the archive limit defaults to 200 MiB. The staged archive is deleted after success, failure, or cancellation.

​
Follow or detach

By default, the CLI follows the build SSE stream, fetches the final build, requires a success status, then polls for the active deployment created from that build. --detach returns as soon as the build is queued. Its result contains the project and build, but no active deployment.

​
Cancellation

Ctrl-C cancels archive walking and reads, upload, log streaming, and deployment polling. Cancellation returns exit code 130 and removes a staged local archive.

​
Expected result

The command returns the project, build, final status, deployment, and URL, or a non-zero failure.

​
Common failures

  • The project has no connected source for the requested Git ref.
  • A local archive exceeds the server upload limit.
  • A symlink is absolute or escapes the selected source root.
  • The build finishes with a status other than success.
  • The matching deployment does not become active before polling ends.

Logs, remote execution, and environment variables

Inspect runtime output, execute structured commands, and mutate environment variables safely.

Output, pagination, errors, and automation

Select stable machine output, fetch paginated results, and handle documented exit codes.