Publish from Git

Push to a Spacefast remote or connect GitHub, choose which branches build, and control which versions go live

Keep your source in Git and publish from a Spacefast remote or a connected GitHub repository. Connected repository pushes queue builds only when auto-deploy is enabled for that branch; deleting a branch does not build it.

Two lanes. The Spacefast remote needs no external host and no app install. A GitHub connection keeps your repository where it is and reacts to its webhooks.

The sf git and sf source command families name the same two connection types in different words — on purpose, not a typo.

Source and deployment files

sf publish dist --prebuilt uploads the files in dist, not the editable project that produced them. A version’s Git commit metadata records where a build came from; it does not mean your source or Git history was uploaded.

Keep the editable project in Git. Connect its repository or push it to the Spacefast remote below. Add and commit the source files before pushing. A Git push transfers the committed history on the branch you push; it excludes files you have not committed. Keep an independent copy of your source and history for recovery. Rolling back a deployment restores published files, not deleted source files or branches.

Push to a Spacefast remote

Spacefast hosts a Git endpoint. sf git origin mints a signed remote and installs it.

sf git origin

sf builds ls

The remote URL carries its credential in the userinfo, with t as the user and an sfp_ token as the password.

https://t:sfp_v1.xxxxxxxx@git.spacefast.com/my-app

Treat that URL as a secret. It expires, and the sf git origin receipt reports expiresInSeconds. Re-run sf git origin to refresh it in place, which updates the existing remote rather than adding another.

sf git origin also creates the Space’s repository connection if it does not have one, so there is nothing else to set up.

Connect a GitHub repository

sf git connect --space docs --provider github --repository owner/repo --production-branch main --sync

GitHub connections resolve their installation and repository ids from your GitHub App installations, so --repository owner/repo is enough. When several installations grant the same repository, pass --installation-id to pick one.

--apply-best, --sync, and --build-now need --connection-type=connected and exit 2 otherwise. So does connecting with neither --repository nor a git origin to read it from.

In the dashboard the same flow lives on the space’s Builds page. Click Connect GitHub, then Connect repository, and pick an Installation and a Repository. Add repositories takes you back to GitHub to widen the installation.

Once connected, the sidebar’s Code row shows Source, the repository tree at the production branch, instead of the version’s files.

Which branch publishes what

The connection carries one production branch. Everything else is a preview.

Both are on by default. Turn one off and pushes to that side still record a delivery but queue no build. The dashboard’s Publish on every push toggle flips to Publishing on push paused, and its hint says webhooks stay visible while no builds are queued.

sf git update --space docs --production-branch main --no-auto-deploy-previews

Force a target by hand when you need to.

sf git build --space docs --ref main --target production --wait

sf git build waits by default, polling once a second up to a 900-second timeout. --no-wait returns as soon as the build is queued. --branch, --commit, and --pull-request set the preview alias and metadata, and each has an environment variable so CI can pass them without flags.

Source builds

The platform builds your repository and publishes the output. It detects the framework and fills in the commands, so an unconfigured repository usually works.

Detected presets include Astro, Next, Nuxt, SvelteKit, Remix, TanStack Start, Vite, Solid Start, Qwik, Angular, Ember, Gatsby, Docusaurus, Eleventy, VitePress, Nextra, Hugo, Jekyll, Zola, MkDocs, and Sphinx. See Frameworks.

Override any of it in sf.jsonc or on the connection.

{
  "build": {
    "rootDirectory": "apps/web",
    "installCommand": "pnpm install",
    "buildCommand": "pnpm build",
    "outputDirectory": "dist",
    "timeoutSeconds": 900
  }
}

The dashboard’s Build settings section holds the same four fields as Root directory, Install command, Build command, and Output directory, each with an Auto placeholder. Leave a field empty and the builder decides from the detected framework. Detect build settings re-runs detection and shows candidates with a confidence, which you can Apply.

Every run appears under Runs on the Builds page, and a run’s detail view carries Commit, Pull request, Started, Duration, Artifact, a Diagnostics section, and a Pipeline section holding the settings snapshot the run built with. The log pane streams while the build runs.

From the CLI:

sf builds ls
sf builds logs bld_123 --follow

See Logs.

Webhook deliveries

Every push the platform hears about is recorded as a delivery, whether or not it produced a build. That is where to look when a push seems to have done nothing.

Open Builds and expand Repository events. A delivery carries a status of received, processing, processed, ignored, or failed, plus the builds it queued and the versions it retired. ignored is the normal answer when auto-deploy is off for that branch.

The API exposes the same list.

Managing the connection

sf git ls --space docs
sf git sync --space docs --ref main
sf git update --space docs --credential "$TOKEN"
sf git disconnect --space docs
sf git github installations --space docs
sf git github repos <installation> --space docs

sf git update takes --clear-credential to remove a stored token, and passing it together with --credential is a validation error. sf git disconnect confirms first. Disconnecting stops pushes from building the Space. What is already published stays live and your domains do not move. The repository itself is untouched.

Two connection-type vocabularies

The exact values each command family uses:

--connection-type defaults to connected on the git commands and to remote on most source commands. Which commands require it, and which values each one takes, is on sf git and sf source.