# Preview environments
URL: https://openship.io/docs/guides/preview-environments.md

Make a separate, safe copy of your project from a git branch — so you can try changes before they reach your real site.

import { Step, Steps } from 'fumadocs-ui/components/steps';

Say you have a project that's already live, and you want to try something risky — a new design, a big rewrite —
without breaking the version real people are using. An **environment** lets you do exactly that. Think of it
like a rehearsal stage set up right next to the main one: same script, same props, but the audience only ever
watches the main stage. You practice on the side, and only move things across when you're happy.

In Openship, each environment is its own copy of the project. It follows its own git branch and gets its own
web address, so your `production` site and a `preview` copy never step on each other.

<Callout title="What you need first">
- A project that's already set up in Openship (see [Deploy from GitHub](/docs/guides/deploy-from-github) if you don't have one yet).
- The project connected to **GitHub**, with more than one branch — an environment is built from a branch.
- A branch to point it at (for example a `staging` or `preview` branch).
</Callout>

## What "production" and "preview" mean

Two words show up a lot here. In plain terms:

- **Production** — the real thing. This is the copy your visitors see. It follows your main branch (usually
  `main` or `master`).
- **Preview** — a practice copy. It follows some other branch, lives at its own separate web address, and can
  have its own environment variables (its own secrets and settings). Break it all you like — production doesn't
  notice.

Openship decides which type a new environment is by looking at its branch:

- A branch named `main` or `master` becomes a **production** environment.
- Any other branch becomes a **preview** environment.
- If you create one by hand without a branch, it's a **development** environment.

Each environment is a full, independent copy: its own address, its own variables, its own deploy history. What
they share is the build recipe — when you create one, Openship copies the original project's framework, build
commands, and settings so you don't set them up again.

## Create an environment from a branch

You do this from the project's page, using the **environment switcher** — the little pill at the top that shows
the current environment's name and its branch.

<Callout title="Screenshot">The project page header showing the environment switcher pill (environment name + branch) with a **+** button beside it. *(screenshot pending)*</Callout>

<Steps>

<Step>

### Open the project and find the switcher

Go to your project. At the top you'll see a rounded button showing the current environment (for a brand-new
project this just reads **Production** with your main branch next to it). Right beside it is a small **+**
button for adding a branch.

</Step>

<Step>

### Press + and pick a branch

Click the **+**. Openship reads your repository and lists its branches, with a **Search branches** box at the
top to filter a long list. Click the branch you want to base the new environment on.

Openship creates a fresh copy of the project tied to that branch and drops you onto its page. That's it — you're
now looking at the new environment.

<Callout title="Screenshot">The Add-branch panel: a **Search branches** box and a list of repository branches, each with a **+** to add it as an environment. *(screenshot pending)*</Callout>

<Callout title="Tip" type="info">
The name is filled in for you from the branch (a branch called `feature/new-home` becomes "Feature New Home").
Nothing you have to type.
</Callout>

</Step>

<Step>

### Deploy the new environment

The new environment starts empty — creating it doesn't deploy anything yet. Deploy it the same way you deploy
any project: open it and press **Deploy**. When it finishes, this copy has its own live web address, separate
from production.

</Step>

</Steps>

### Switching between environments

Once you have more than one, click the switcher pill to see the full list. Each row shows the environment name
and its branch, with a check mark next to the one you're viewing. Click any row to jump to that copy of the
project — its own deploys, logs, and variables.

<Callout title="Screenshot">The open environment switcher dropdown listing each environment with its branch and a check mark on the current one. *(screenshot pending)*</Callout>

### Creating one by hand (no branch)

At the bottom of the Add-branch panel there's a **Manual environment** option. Use it when you want an
environment that isn't tied to a specific branch yet — you give it a name (and, optionally, a **Branch label**)
and press **Create**. This makes a *development* environment.

## Prefer the terminal?

If you deploy from the CLI, the `deploy` command has an `--env` flag that tells Openship which environment a
deploy is for. It applies that environment's variables and records the deploy under it.

```bash
# Deploy the project your folder is linked to, as production (this is the default)
openship deploy

# Deploy as a preview instead — uses your preview environment's variables
openship deploy --env preview
```

<Callout title="Only two values" type="info">
`--env` accepts exactly `production` or `preview`. Anything else is rejected. If you leave it off, it defaults
to `production`.
</Callout>

Each environment you created in the switcher is its own project with its own ID. To deploy one of those copies
specifically, point the CLI at it with `--project`:

```bash
openship deploy --project <environment-project-id> --env preview --watch
```

`--watch` streams the build logs until it finishes, so you can see it go live right there in your terminal.

## If something goes wrong

<Callout title="No branches show up when I press +" type="warn">
The environment list is built from your GitHub branches, so the project has to be connected to GitHub and have
branches to show. If the list is empty, check that the project is linked to a repository. See
[Deploy from GitHub](/docs/guides/deploy-from-github) for connecting GitHub.
</Callout>

<Callout title="“Branch … was not found”" type="error">
Openship couldn't find that branch in the repository. Make sure the branch actually exists on GitHub (and that
it's pushed, not just local), then try again.
</Callout>

<Callout title="An environment with that name already exists" type="warn">
Each environment under a project needs a unique name. If you already turned that branch into an environment,
switch to it from the pill instead of making a second.
</Callout>

<Callout title="My preview is missing a secret" type="warn">
Variables are per-environment — a preview copy doesn't automatically inherit production's. Open the preview
environment and add what it needs. See [Environment variables](/docs/guides/environment-variables).
</Callout>

## What next?

<Cards>
  <Card title="Environment variables" href="/docs/guides/environment-variables" description="Give each environment its own secrets and settings." />
  <Card title="Deploy from GitHub" href="/docs/guides/deploy-from-github" description="The core deploy flow, and how to redeploy automatically on every push." />
  <Card title="Custom domains" href="/docs/guides/custom-domains" description="Put an environment on your own address with automatic HTTPS." />
</Cards>