Create an Environment

Complete the prerequisites first, especially both GitHub connections and repository grants.

Open the editor#

1. 1
   Open Settings → Environments and click New environment.
2. 2
   In the gallery, choose Create your own, or a starter idea such as Ship a web app, Test in a real browser, or Analyze data.
3. 3
   Review the prefilled name and setup script. Starters are editable ideas, not already-built Environments. Choose your own repositories in the next step.

The settings list also has Gallery and List views for existing Environments, with search and filters. First-run guidance appears when there are no Environments.

Set the basics and source#

1. 1
   Enter a Name, such as web-development. Use at most 63 characters: start with a lowercase letter, use lowercase letters, numbers, and hyphens, and do not end with a hyphen.
2. 2
   Choose Authorization:

   • Only me creates a personal Environment.
   • Everyone in my organization creates an organization Environment. This requires manager or owner access.
3. 3
   For an organization Environment, optionally select Make organization-wide default. It becomes the default when its build is Ready, not while it is building. Members still need repository access.
4. 4
   Choose a Provider and Source. The default is Factory managed with Factory default. Other configured sources may appear for your organization.

Some sources do not support repository cloning or setup scripts. The editor shows only supported build options. Switching to a source that cannot retain your configuration asks you to confirm Remove and switch; review what will be removed before continuing.

Configure build steps#

The build runs in this order:

1. 1
   Clone repositories: click Add repository, search, select repositories, and click Done. Repositories must have distinct final directory names; for example, two repositories both named api cannot be included together.
2. 2
   Setup script: optionally install tools shared across repositories. On the Factory-managed source, this script runs from the user's home directory, not from a repository.
3. 3
   Repository setup scripts: expand a selected repository's script row and add commands for that repository. Each script runs in its repository directory, after the global setup.

For a repository using npm with a committed lockfile, a repository setup script might be:

npm ci
npm run build

Use your repository's actual package manager and build commands. Build scripts run with Bash and stop on command failures. Prefer commands that do not prompt for input, pinned tool versions, and commands that can run again safely. Installing a tool during a build does not mean a long-running service will automatically start in every new instance.

You may create an Environment without repositories or scripts. For repository-backed Environments, the current limit is 200 repositories. Each setup script can contain at most 10,000 characters; the combined repository scripts are limited to 256 KiB.

Runtime secrets from Settings → Account → Secrets are not supplied to these build steps. See runtime secrets before adding commands that need credentials.

Create and wait for the first build#

Click Create. Factory saves the Environment and starts its first build. Open it from the list to see progress, build output, and any failure reason.

The Environment is not usable for sessions until its first build is Ready. If the build fails, fix the cause and retry.

When creating from a delegation or Mission chooser, the same editor may appear as a two-step dialog: Environment details, then Build steps. A shared delegation Environment is locked to organization authorization.