# Deploying

A new version of your app can reach Nimbus Land in four ways. Two happen on their own once you turn them on: a push to your branch, and a preview for each pull request. The other two you start yourself: `nimbus deploy` from your machine, and a CI job with a deploy token.

You'll find all of them on your app's **Deployments** tab. A static site works the same way; the console says "publish" where it says "deploy" for an app.

## Push to deploy

With a GitHub repository connected, **Deploy on push to `main`** (or whichever branch you chose) builds and deploys every push to that branch. While it's off, pushes do nothing, and you ship a new version with **Deploy** on the app's **Overview**.

Turning it on asks you to confirm, because:

- anyone who can push to that branch, including bots and automation with write access, can start a deploy;
- those deploys run as you, and the audit log records them under your name.

The setting shows who deploys run as and when the last push arrived, so you can tell at a glance whether pushes are reaching Nimbus Land.

## Previews

With **Preview pull requests** on, each pull request gets its own copy of your app at its own address. A new push to the pull request updates its preview, and closing or merging it removes the preview. The pull request shows a check with the preview's address once it is live.

- **Cost.** A preview runs at your app's size, plus its own copy of each included database, while the pull request is open. The setting shows the monthly price of one preview.
- **How many.** Your organization can run up to 10 previews at once. When it reaches the limit, a new pull request gets no preview, and its check and a comment on the pull request say why.
- **Pull requests from forks are never built.** Only branches in your own repository get a preview, so code from outside your team never runs on your account.
- **Data.** Each preview starts with its own empty database, filled by your seed command if you set one. It never sees production's data or secrets. See [Secret environment variables](secret-env-vars.md#staging-and-preview-environments).
- **Who can open them.** **Require sign-in on previews** is on by default: only members of your organization can open a preview, after signing in, even when the app itself is public. Turn it off to let anyone with a preview's link open it. The change applies to running previews right away.

## From your machine

The `nimbus` command-line tool deploys the folder you are in, with or without a repository.

1. Install it. On macOS or Linux with Homebrew:

   ```sh
   brew install nimbus-land/tap/nimbus
   ```

   Without Homebrew:

   ```sh
   curl -fsSL https://get.nimbusland.ca/install.sh | sh
   ```

2. Sign in. Your browser opens to confirm it:

   ```sh
   nimbus login
   ```

3. In your project's folder, deploy:

   ```sh
   nimbus deploy
   ```

`nimbus deploy` uploads the folder, builds it and waits until the new version is live. The **Deployments** tab shows who last shipped this way and when. See [Your first app](first-app.md#deploy-from-your-computer-instead) for more.

## From CI

A CI job deploys with a **deploy token** instead of your own sign-in. A token works for one app only: it can start builds and rebuilds, read build logs and run one-off commands, and nothing else in your organization.

1. On the app's **Access** tab, under **Deploy from CI**, create a token. It is shown once, so copy it.
2. Store it as a secret in your CI provider, named `NIMBUS_TOKEN`.
3. Add these steps to your workflow. For GitHub Actions:

   ```yaml
   - name: Install the Nimbus CLI
     run: curl -fsSL https://get.nimbusland.ca/install.sh | sh
   - name: Deploy to Nimbus Land
     env:
       NIMBUS_TOKEN: ${{ secrets.NIMBUS_TOKEN }}
     run: nimbus deploy
   ```

If a token leaks, revoke it on the **Access** tab. The **Deployments** tab shows how many live tokens the app has.