Skip to main content

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.

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:
ModeWhat’s copiedTypical use
FullSchema and all row data.QA, staging, performance testing — anywhere you need realistic data.
SystemSchema 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 schema between environments later regardless of the mode each one was created in.

​
Creating from the dashboard

1

Open the environment switcher

Click the dropdown showing the active environment’s name at the top of the project chrome.
2

Click + Create Environment

The branching modal opens.
3

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.
4

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.
5

Choose the branch mode

Full for schema + data, System for schema only.
6

Choose what configuration to copy

Tick the configuration checkboxes you want carried over from the source. See What’s copied below for the full list and the security caveat.
7

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.
Environment branching modal with copy options

​
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.
ResourceCheckbox labelCarries over
File storage providersFile storage providersS3, GCS, Azure, Filestack credentials. Each copy gets a new ID.
Custom APIsGateway routesCustom API gateway routes and webhooks.
Network policySecurity configCORS origins and rate-limit settings.
Environment variablesEnvironment variablesKey-value pairs for runtime configuration.

​
What’s never copied

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.
For the full per-environment scoping list, see Configuration. For the auth-provider configuration flow, see Authentication Providers.

​
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.
StepWhat it does
1. ValidationVerifies the name is unique and the source is in active status.
2. Record creationRegisters a new environment record with the project.
3. Database cloningClones the source PostgreSQL database — full data in Full mode, schema only in System mode.
4. Database usersProvisions fresh database credentials, separate from the source.
5. Configuration registrationLinks the new environment to the project.
6. Resource copyingCopies the configuration blocks you ticked.
7. Status activationStatus 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. 
mutation BranchEnvironment($input: BranchEnvironmentInput!) {
  branchEnvironment(input: $input) {
    success
    message
    environment {
      id
      name
      parentId
      parentName
      branchMode
      branchedAt
      status
    }
  }
}

{
  "input": {
    "projectId": "f7e4a264-d659-4719-91e8-c2d74654e529",
    "name": "staging",
    "sourceEnvironment": "master",
    "mode": "full",
    "copyFileProviders": true,
    "copyGatewayRoutes": true,
    "copySecurityConfig": false,
    "copyEnvironmentVariables": true
  }
}
FieldTypeRequiredDescription
projectIdStringYesThe project’s unique identifier.
nameStringYesName for the new environment.
sourceEnvironmentStringYesName of the source environment.
modeStringYes"full" or "system".
copyFileProvidersBooleanNoCopy file storage configurations.
copyGatewayRoutesBooleanNoCopy custom API gateway routes.
copySecurityConfigBooleanNoCopy CORS and rate limit settings.
copyEnvironmentVariablesBooleanNoCopy environment variable key-value pairs.
Enabling any copy flag requires the ProjectOwner role. Without copy flags, standard project access is enough.

​
FAQ

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.
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.
The copy flags only apply at branch time. After branching, edit each environment’s variables individually under Settings → Environment Variables. For shared values you don’t want to edit twice, look at workspace-level secrets.
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.
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.