> ## Documentation Index
> Fetch the complete documentation index at: https://archie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating environments

> Branch a new environment from any active source. Pick a branch mode, choose what configuration to copy, and decide what stays per-environment.

You create an environment by branching from any **active** source. The platform clones the source database, optionally copies configuration resources, and gives you an isolated workspace for development, testing, or staging changes.

## Branch modes

Pick how the source database is cloned:

| Mode       | What's copied                                                                 | Typical use                                                          |
| ---------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Full**   | Schema **and** all row data.                                                  | QA, staging, performance testing — anywhere you need realistic data. |
| **System** | Schema only — tables, columns, indexes, relationships, enums, views. No data. | Clean dev environments, feature branches you'll seed yourself.       |

The mode is set at branch time and recorded on the environment. You can always [merge](/features/backend/environments/merge) schema between environments later regardless of the mode each one was created in.

## Creating from the dashboard

<Steps>
  <Step title="Open the environment switcher">
    Click the dropdown showing the active environment's name at the top of the project chrome.
  </Step>

  <Step title="Click + Create Environment">
    The branching modal opens.
  </Step>

  <Step title="Pick the source environment">
    The **Branch From** dropdown lists every environment in `active` status. Environments in `branching`, `merging`, or `error` aren't available as sources until they settle.
  </Step>

  <Step title="Name the new environment">
    Names accept alphanumeric characters, hyphens, and underscores — `staging`, `feature-auth`, `qa-sprint-12`. They have to be unique within the project.
  </Step>

  <Step title="Choose the branch mode">
    **Full** for schema + data, **System** for schema only.
  </Step>

  <Step title="Choose what configuration to copy">
    Tick the configuration checkboxes you want carried over from the source. See [What's copied](#what-s-copied) below for the full list and the security caveat.
  </Step>

  <Step title="Click Create environment">
    The platform validates the name, clones the database, registers the new environment, and copies any selected configuration. Status flips from `branching` to `active` once everything's in place.
  </Step>
</Steps>

<img src="https://mintcdn.com/archie-e998dbf6/JNerAbEOM8n69x8B/features/blueprint/github-repo-branch-config.png?fit=max&auto=format&n=JNerAbEOM8n69x8B&q=85&s=a1e9e458e9556393c8727c5d36169c6d" alt="Create new environment modal with branch mode and copy options" width="2880" height="1800" data-path="features/blueprint/github-repo-branch-config.png" />

## What's copied

Each configuration block has its own checkbox. The `ProjectOwner` role is required to enable any of these — they involve carrying sensitive configuration across boundaries.

| Resource               | Checkbox label             | Carries over                                                    |
| ---------------------- | -------------------------- | --------------------------------------------------------------- |
| File storage providers | **File storage providers** | S3, GCS, Azure, Filestack credentials. Each copy gets a new ID. |
| Custom APIs            | **Gateway routes**         | Custom API gateway routes and webhooks.                         |
| Network policy         | **Security config**        | CORS origins and rate-limit settings.                           |
| Environment variables  | **Environment variables**  | Key-value pairs for runtime configuration.                      |

## What's never copied

<Warning>
  **Authentication provider secrets and OAuth credentials are never copied** when branching, even if you tick every other checkbox. OAuth client secrets, Cognito credentials, Auth0 tenant keys, and similar credentials must be configured independently in each environment. This is a deliberate isolation boundary so a leaked `dev` secret can't be replayed against `production`.
</Warning>

For the full per-environment scoping list, see [Configuration](/features/backend/environments/configuration). For the auth-provider configuration flow, see [Authentication Providers](/features/backend/app-services/authentication-providers/overview).

## What happens during branching

When you click **Create environment**, the platform runs the following steps. If any step fails, everything rolls back — the new database is dropped, credentials are revoked, and no orphaned resources are left behind.

| Step                          | What it does                                                                                    |
| ----------------------------- | ----------------------------------------------------------------------------------------------- |
| 1. Validation                 | Verifies the name is unique and the source is in `active` status.                               |
| 2. Record creation            | Registers a new environment record with the project.                                            |
| 3. Database cloning           | Clones the source PostgreSQL database — full data in `Full` mode, schema only in `System` mode. |
| 4. Database users             | Provisions fresh database credentials, separate from the source.                                |
| 5. Configuration registration | Links the new environment to the project.                                                       |
| 6. Resource copying           | Copies the configuration blocks you ticked.                                                     |
| 7. Status activation          | Status transitions from `branching` to `active`.                                                |

While branching is in progress, the new environment is visible in the switcher with a `branching` status indicator. You can switch to it once it goes `active`.

## Creating via GraphQL

Use the `branchEnvironment` mutation to create environments programmatically — useful for codifying environment creation alongside infrastructure-as-code.

```graphql theme={null}
mutation BranchEnvironment($input: BranchEnvironmentInput!) {
  branchEnvironment(input: $input) {
    success
    message
    environment {
      id
      name
      parentId
      parentName
      branchMode
      branchedAt
      status
    }
  }
}
```

```json theme={null}
{
  "input": {
    "projectId": "f7e4a264-d659-4719-91e8-c2d74654e529",
    "name": "staging",
    "sourceEnvironment": "master",
    "mode": "full",
    "copyFileProviders": true,
    "copyGatewayRoutes": true,
    "copySecurityConfig": false,
    "copyEnvironmentVariables": true
  }
}
```

| Field                      | Type    | Required | Description                                |
| -------------------------- | ------- | -------- | ------------------------------------------ |
| `projectId`                | String  | Yes      | The project's unique identifier.           |
| `name`                     | String  | Yes      | Name for the new environment.              |
| `sourceEnvironment`        | String  | Yes      | Name of the source environment.            |
| `mode`                     | String  | Yes      | `"full"` or `"system"`.                    |
| `copyFileProviders`        | Boolean | No       | Copy file storage configurations.          |
| `copyGatewayRoutes`        | Boolean | No       | Copy custom API gateway routes.            |
| `copySecurityConfig`       | Boolean | No       | Copy CORS and rate limit settings.         |
| `copyEnvironmentVariables` | Boolean | No       | Copy environment variable key-value pairs. |

Enabling any copy flag requires the `ProjectOwner` role. Without copy flags, standard project access is enough.

## FAQ

<AccordionGroup>
  <Accordion title="Should I pick Full or System mode?">
    Full when you need realistic data — staging, QA, anything resembling production traffic. System when you want a clean, schema-only environment to seed however you like (test fixtures, scripted data). The mode is recorded but doesn't constrain future merges.
  </Accordion>

  <Accordion title="Why aren't auth provider secrets copied?">
    Deliberate isolation. Sharing OAuth client secrets across environments means a leak in `dev` compromises `production`. Re-entering credentials per environment makes the security boundary explicit and reviewable.
  </Accordion>

  <Accordion title="Can I copy environment variables after branching?">
    The copy flags only apply at branch time. After branching, edit each environment's variables individually under [Settings → Environment Variables](/features/backend/settings/environment-variables). For shared values you don't want to edit twice, look at workspace-level secrets.
  </Accordion>

  <Accordion title="What happens if branching fails halfway through?">
    The platform automatically rolls back. The cloned database and credentials are dropped, and the partially-registered environment record is removed. Your source environment is never touched by a failed branch.
  </Accordion>

  <Accordion title="How long does branching take?">
    Depends on the source database size in **Full** mode. **System** mode is fast — schema-only clones complete in seconds. Full clones scale with row count and can take a few minutes for large databases. The status indicator stays at `branching` until the clone completes.
  </Accordion>
</AccordionGroup>