Visual Editor /Cloud project /

Create from Git Repository

Visual Editor supports the ability to create new cloud projects from an existing Git repository or by duplicating a public repository.


To learn more about how Visual Editor creates a project and provisions the appropriate services, visit How the visual editor works.

The following Git service providers are supported:

  • Bitbucket
  • Git

# Project preparation

Cloud projects are typically created when teams are ready to begin collaborating on visually editing a site.

# Prerequisites

Cloud projects can only be created from valid Visual Editor projects. A valid Visual Editor project contains the following:

  • Content: Content that is separated from code and structured.
  • Configuration: A valid configuration file file.
  • Framework/Runtime: A Node.js-based site framework using Node v14 or newer.
  • Content Source: Proper API CMS configuration (if necessary). This depends on your content source and create mode.

# Create modes

When creating a new project, you can choose to connect to an existing Git repository, or Visual Editor can duplicate an existing repository. This is done by clicking the Create from git repository button on the new project screen.

# Mode: use my repository

When using an existing repository, Visual Editor project will use the specified repository directly. This means that any changes made to the branch that content editors are using (preview by default) will be reflected in Visual Editor project.

Each Git service provider is presented as an option.

Choosing one of the use my repository options will lead to the appropriate authentication method prior to inserting the repository URL.

# Configure a headless CMS

If your site is using a headless CMS as a content source (as defined in Visual Editor configuration file), you will be prompted to connect Visual Editor to the relevant CMS and select an existing space/dataset/environment (the terminology depends on the CMS).

# Mode: duplicate a repository

You also have the option to create a new project from a remote Git repository you can access from one of the supported providers. Visual Editor duplicates that repository and creates a new cloud project based on the duplicated code.

# Transfer repository ownership

When duplicating a repository, Visual Editor pushes the duplicated code to a Visual Editor-owned repository.

After the project is created, you can transfer the repository to a Git account or organization that you own. This will allow you to clone its contents to your local machine, push changes, modify branches, and so on.

You can later rename or move the repository as you wish and Visual Editor will update automatically.

# Import content into a headless CMS

The repository you used to create a new project may be configured to use a headless CMS (via the import configuration option).

For the creation process to work properly, your CMS account needs to be bootstrapped with the proper content model and initial content. After you connect Visual Editor to your CMS account (when prompted), Visual Editor creates and initializes a new space/dataset (to avoid content conflicts), then imports the data models and content.

# Needed permissions

To operate correctly with your repository, Visual Editor needs the ability to commit and merge code, create branches and add a webhook. Because Visual Editor operates on behalf of a Git user, your Git user must have the necessary read and write permissions on the repository.

How your Git user is connected to Visual Editor depends on the Git service provider you're using. You will be guided through the process after choosing the appropriate provider.

# Advanced options

There are a number of advanced customizations you can make while creating a new cloud project.

# Custom Git branches

When creating a new project, Visual Editor either infers or has sensible defaults for the Git branches it uses:

  • Target Branch (production): Matches the repository's primary branch (usually main or master).
  • Working Branch (development/editing): Defaults to preview, and is automatically created for new projects when it doesn't exist.

You can make adjustments to these defaults as needed during the project creation process, or any time through the visual editor settings. Learn more about Git branches in Visual Editor.

# Monorepo support

Visual Editor supports monorepo configurations — repositories that contain multiple Visual Editor configuration files — through the site root directory option, which you can adjust after choosing a repository.

Revalidate after changing site root

Visual Editor automatically validates repositories in Use my Repository mode. In this case, the first attempt at validation for monorepos typically fails because Visual Editor validates against the root directory.

After you change the site root directory, you can click Revalidate to run the validation again. You won't be able to proceed without a valid site.

If you have a more complex monorepo layout and are unsure how to bring it into Visual Editor, talk to us!

# Organizations

Customers using a paid Visual Editor plan have an organization entity in Visual Editor, through which permissions and projects are centrally managed. Organization admins have the option to place new projects within a specific organization.

Otherwise, new projects are automatically added to your personal account.