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

​
Goal

Create a project that follows the GitHub-driven build and deployment path.

​
Prerequisites

  • GitHub connected
  • A repository StackShift can access

​
Workflow

1
Create a project from a GitHub repository.
2
Confirm framework/runtime detection and review the Advanced / Runtime section.
3
Override service type, workload type, resource preset, timeout, web3 detection, or persistent storage if the defaults are wrong.
4
Trigger the initial build and watch build output and deployment state.
5
Use subsequent pushes or manual redeploys as needed.

​
Simplified deployment review (pending API, worker and frontend release)

Repository, folder and container-image sources use source selection followed by Review & Deploy. Valid detection does not require a generic confirmation. Advanced contains build commands, ports, processes, runtime limits and storage overrides; Change destination selects hosted or a healthy connected server. Source analysis allocates bounded temporary mounts for recognized cache and temp paths and a 1 GB persistent volume for other supported write locations. Persistent allocations remain subject to your plan and normal storage rules. Review shows the allocation before Deploy. Recognized literal SQLite paths are retained. Apps writing beside their code or across incompatible directories receive a specific correction instead. Environment-dependent paths are checked at build time against the effective runtime settings; source-only analysis does not treat an optional database fallback as mandatory storage. Changing repository, source type, branch or app directory clears the previous source’s environment values. Folder imports use only the selected directory, in precedence order .env, .env.production, .env.local, .env.production.local; development and example values are not imported. A failed replacement upload preserves the previous draft. Project creation and build submission reuse a stable key for retries. Once a project exists, retry continues its environment setup and initial build rather than creating another project. Drafts and source documents stay in memory; leaving the page warns before losing them. Refresh recovery is not provided and secrets are never persisted in browser storage. Multi-service manifests continue to Applications with their document and source/ref context. Review repositories and branches there before applying. Application releases still require GitHub sources; uploaded Application releases and automatic conversion of older manifest schemas are not supported. This workflow is implemented locally and requires the coordinated API, worker and frontend release. The existing node-agent storage contract handles the declared mounts; no new migration or environment setting is introduced.

​
How StackShift builds your app

  • Shiftpack is the native build engine: it detects your framework and runtime, then builds straight to an OCI image without you writing a Dockerfile.
  • It builds with BuildKit under the hood, so dependency caching and reproducible images come for free.
  • If your repo has its own Dockerfile and you point StackShift at it, that takes over instead of Shiftpack.

​
What this path includes

  • Repository-backed project creation
  • Build and deployment lifecycle visibility
  • Project-level logs, domains, and rollback surfaces after deploy

​
What usually decides success

  • Repository access and installation scope
  • Correct build/runtime detection for the app
  • Post-build runtime configuration such as service type, workload type, ports, env vars, timeouts, and domains

​
How web3 detection behaves

  • StackShift can auto-detect common web3 frameworks and dependencies and mark the project as web3-enabled.
  • The detected value is still user-overridable in case the repo shape or dependency tree gives the wrong signal.
  • Hardhat-, Foundry-, and Anchor-style contract repos often fit contract-build workloads better than always-on web services.

​
Expected result

The project is connected to a GitHub repo and can build and deploy through StackShift.

​
Common failures

  • Repo permissions are incomplete
  • Build settings do not match the app runtime
  • Build succeeds but deploy fails due to runtime config

Connect GitHub

Link GitHub so project-style deployments can pull repositories and deployment metadata cleanly.

Builds, deployments, and logs

Understand the project execution lifecycle: build output, deploy state, rollback behavior, and where to inspect logs.

Project environment, domains, and previews

Configure the project surfaces that most often decide whether a deployment works after it builds, including runtime shape, domains, previews, and storage.